opencode-sovereign-auth

An OpenCode 1.18.23 provider auth plugin for a sovereign OpenAI-compatible gateway. It registers the sovereign provider with the logical models local and auto, and adds Sign in with Microsoft to /connect.

The plugin uses the Microsoft Entra authorization-code flow with PKCE S256. It is a public client and never accepts or sends a client secret.

Prerequisites

Create an Entra app registration that:

• permits the intended Microsoft account/organizational tenant audience through the /common endpoint;
• registers http://localhost:1456/auth/callback as a redirect URI for a public/native client;
• exposes the delegated scope access_as_user;
• permits public client authorization-code flows with PKCE.

The requested scope is:

openid profile email offline_access api://CLIENT_ID/access_as_user

Install

Run the automated setup:

npx opencode-sovereign-auth@latest setup

It preserves existing JSONC comments and settings, creates a timestamped backup, adds the plugin, sets sovereign/local only when no default exists, and starts Microsoft login. Use --set-default to replace an existing default model or --no-login to configure without authenticating.

On Windows, setup checks the system PATH and common npm, official installer, Scoop, Chocolatey, WinGet, and desktop installation locations. If only the desktop application is installed, open OpenCode after setup and run /connect → Sovereign Inference → Sign in with Microsoft.

To remove it:

npx opencode-sovereign-auth@latest uninstall

Alternatively, add the published package manually. OpenCode installs it automatically; testers do not run npm install.

{
  "plugin": ["[email protected]"]
}

For a local checkout, build the package and use an absolute file:// URL to its dist/index.js as the plugin specifier.

Configuration can instead come from the environment:

export SOVEREIGN_ENTRA_CLIENT_ID="00000000-0000-0000-0000-000000000000"
export SOVEREIGN_API_URL="https://gateway.example.com/v1"

Package options take precedence over environment variables. The public Entra client ID and https://sip-poc.theodorelheureux.com/v1 endpoint are baked in. Distribution-specific defaults are isolated in BAKED_DEFAULTS.

Set openBrowser to false in package options for a headless environment. OpenCode still displays the authorization URL.

Run /connect, select sovereign, then choose Sign in with Microsoft. The callback listener binds only to localhost port 1456 and stops after completion or timeout.

Security behavior

• OAuth state uses 256 bits of randomness and constant-time verification.
• PKCE uses S256 and a cryptographically random verifier.
• Refresh occurs 60 seconds before access-token expiry and persists refresh-token rotation through OpenCode.
• The custom fetch refuses to attach the access token to an origin or URL path outside the configured gateway.
• Credentials, prompts, responses, and traces are not logged.

Development

npm ci
npm run typecheck
npm test
npm pack --dry-run