feat: add companion pairing API by ttupper92618 · Pull Request #146 · Foxlight-Foundation/Skulk

ttupper92618 · 2026-05-05T15:03:54Z

Summary

Adds the Skulk-side native companion pairing surface for SkulkOps Pair and Observe.

Adds short-lived companion pairing sessions with QR payload metadata
Exchanges single-use nonces for scoped read-only bearer credentials
Stores only hashed companion credentials and persists them across Skulk restarts
Adds an Ed25519 cluster public key for cluster binding
Adds a companion-safe read-only overview endpoint

Security Notes

QR payloads do not contain bearer credentials
Tailscale/LAN remains reachability only; companion bearer credentials are the authorization boundary
V1 credentials are scoped to read-only observation
Credential hashes and cluster key material are stored under Skulk config with 0600 permissions
Destructive operations are not exposed through the companion API

Validation

uv run ruff check src/exo/api/companion.py src/exo/api/main.py src/exo/api/tests/test_companion_api.py src/exo/shared/constants.py
uv run pytest src/exo/api/tests/test_companion_api.py src/exo/api/tests/test_connectivity_api.py
uv run basedpyright src/exo/api/main.py src/exo/api/companion.py src/exo/api/tests/test_companion_api.py

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 12f09dd620

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Adds a Skulk-side “Companion” API surface that supports QR-based pairing, nonce exchange into revocable read-only bearer credentials, and a companion-safe cluster overview endpoint.

Changes:

Introduces CompanionPairingManager + Pydantic contracts to create short-lived pairing sessions, exchange nonces for scoped bearer tokens, and persist hashed credentials.
Wires new /v1/companion/* endpoints into the main FastAPI app, including bearer-token authentication for the overview endpoint.
Adds cryptography dependency and a test suite covering pairing/session expiry, single-use nonces, credential persistence, and auth enforcement.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
uv.lock	Locks updated dependency graph including `cryptography` wheels/markers.
pyproject.toml	Adds `cryptography>=46.0.0` to runtime dependencies.
src/exo/shared/constants.py	Adds config paths for companion cluster key + credential store (and EXO_* aliases).
src/exo/api/companion.py	New companion pairing/credential store implementation + overview response builder.
src/exo/api/main.py	Registers Companion routes and integrates pairing manager + auth enforcement.
src/exo/api/tests/test_companion_api.py	New tests validating pairing session creation, nonce exchange rules, auth, revocation, and persistence.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8af05a407f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a106ff13f4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 882a61e2c5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a19a19e8a0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 55b7c325a1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 8 comments.

Files not reviewed (1)

dashboard-react/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d17d9ac1f2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 57ad192083

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9511d36df8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

dashboard-react/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

dashboard-react/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

dashboard-react/package-lock.json: Language not supported

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1ed98c92e3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

dashboard-react/package-lock.json: Language not supported

chatgpt-codex-connector · 2026-05-06T15:10:42Z

💡 Codex Review

Skulk/src/exo/api/main.py

Lines 529 to 530 in 1e8105f

    
           host = request.client.host if request.client else "" 
        
           if not _is_loopback_host(host):

Handle missing client info in loopback authorization

_is_loopback_client assumes request.client is always present, but Starlette allows it to be None (for example, common Uvicorn deployments behind a UNIX domain socket). In that case host becomes "", this check returns False, and _require_companion_pairing_operator rejects otherwise local operator requests unless an explicit token header is configured. This causes companion QR creation to fail in valid local proxy setups that should pass loopback auth.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copilot

Pull request overview

Copilot reviewed 11 out of 14 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

dashboard-react/package-lock.json: Language not supported

+            return {}
+        try:
+            store = CompanionCredentialStore.model_validate_json(
+                self._credentials_path.read_text()


feat: add companion pairing api

12f09dd

Copilot AI review requested due to automatic review settings May 5, 2026 15:03

Copilot started reviewing on behalf of ttupper92618 May 5, 2026 15:04 View session

chatgpt-codex-connector Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/exo/api/main.py

Copilot AI reviewed May 5, 2026

View reviewed changes

fix: harden companion pairing review issues

8af05a4

chatgpt-codex-connector Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/exo/api/companion.py Outdated

feat: expose companion pairing in observability

a106ff1

Copilot AI review requested due to automatic review settings May 5, 2026 17:58

Copilot started reviewing on behalf of ttupper92618 May 5, 2026 17:58 View session

chatgpt-codex-connector Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/exo/api/main.py Outdated

Comment thread src/exo/api/companion.py Outdated

Copilot AI reviewed May 5, 2026

View reviewed changes

Comment thread src/exo/api/main.py

Comment thread dashboard-react/src/components/observability/PairingTab.tsx

Comment thread src/exo/api/companion.py

Comment thread src/exo/api/companion.py Outdated

Comment thread src/exo/api/companion.py Outdated

fix: harden pairing loopback trust

882a61e

chatgpt-codex-connector Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/exo/api/companion.py Outdated

fix: recover corrupted companion cluster key

a19a19e

Copilot AI review requested due to automatic review settings May 5, 2026 18:26

Copilot started reviewing on behalf of ttupper92618 May 5, 2026 18:27 View session

chatgpt-codex-connector Bot reviewed May 5, 2026

View reviewed changes

Comment thread dashboard-react/src/components/observability/PairingTab.tsx Outdated

Comment thread src/exo/api/main.py Outdated

Copilot AI reviewed May 5, 2026

View reviewed changes

Comment thread src/exo/api/companion.py Outdated

Comment thread src/exo/api/companion.py Outdated

Comment thread src/exo/api/companion.py Outdated

Comment thread src/exo/api/main.py Outdated

Comment thread src/exo/api/companion.py Outdated

Comment thread src/exo/api/companion.py Outdated

fix: keep pairing qr during renewal

55b7c32

chatgpt-codex-connector Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/exo/api/main.py Outdated

refactor: use React QR code component

d17d9ac

Copilot AI review requested due to automatic review settings May 5, 2026 21:33

Copilot started reviewing on behalf of ttupper92618 May 5, 2026 21:33 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed May 5, 2026

View reviewed changes

Comment thread src/exo/api/companion.py

fix: address companion pairing review threads

57ad192

chatgpt-codex-connector Bot reviewed May 6, 2026

View reviewed changes

Comment thread src/exo/api/main.py Outdated

fix: harden companion pairing loopback auth

9511d36

Copilot AI review requested due to automatic review settings May 6, 2026 02:37

Copilot started reviewing on behalf of ttupper92618 May 6, 2026 02:37 View session

chatgpt-codex-connector Bot reviewed May 6, 2026

View reviewed changes

Comment thread src/exo/api/main.py Outdated

Copilot AI reviewed May 6, 2026

View reviewed changes

Comment thread src/exo/api/main.py Outdated

Comment thread src/exo/api/companion.py Outdated

Comment thread src/exo/api/companion.py Outdated

ttupper92618 added 2 commits May 5, 2026 21:46

fix: require trusted companion pairing loopback requests

3c71bf7

fix: tighten companion pairing trust checks

54b6333

Copilot AI review requested due to automatic review settings May 6, 2026 03:19

Copilot started reviewing on behalf of ttupper92618 May 6, 2026 03:19 View session

Copilot AI reviewed May 6, 2026

View reviewed changes

Comment thread src/exo/api/companion.py Outdated

Comment thread src/exo/api/companion.py Outdated

Comment thread src/exo/api/main.py

Comment thread dashboard-react/src/components/observability/PairingTab.tsx Outdated

ttupper92618 added 2 commits May 6, 2026 09:10

fix: stabilize companion pairing manager

06644d9

fix: abort pairing renewal cleanup

df75a98

Copilot AI review requested due to automatic review settings May 6, 2026 14:11

Copilot started reviewing on behalf of ttupper92618 May 6, 2026 14:12 View session

Copilot AI reviewed May 6, 2026

View reviewed changes

Comment thread src/exo/api/main.py Outdated

Comment thread src/exo/api/companion.py Outdated

ttupper92618 added 2 commits May 6, 2026 09:33

fix: clean up companion pairing URL guards

a2502ec

fix: cap companion credentials

1ed98c9

Copilot AI review requested due to automatic review settings May 6, 2026 14:37

Copilot started reviewing on behalf of ttupper92618 May 6, 2026 14:38 View session

chatgpt-codex-connector Bot reviewed May 6, 2026

View reviewed changes

Comment thread src/exo/api/companion.py Outdated

Copilot AI reviewed May 6, 2026

View reviewed changes

Comment thread src/exo/api/main.py

fix: refine companion pairing limits

1e8105f

chore: ignore vector buffer artifacts

11b76e6

Copilot AI review requested due to automatic review settings May 12, 2026 05:42

Copilot started reviewing on behalf of ttupper92618 May 12, 2026 05:43 View session

Copilot AI reviewed May 12, 2026

View reviewed changes

Comment thread src/exo/api/companion.py

return {}

try:

store = CompanionCredentialStore.model_validate_json(

self._credentials_path.read_text()

Uh oh!

Conversation

ttupper92618 commented May 5, 2026

Summary

Security Notes

Validation

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!