opencode-muse-auth 0.3.0 → 0.4.1

package/AUTH_CONTRACT.md

@@ -0,0 +1,32 @@
+# Muse auth contract (v1)
+
+The three Muse Code plugins implement the same Meta device-code flow. Change
+this file and the pinned constants/tests together in all three repositories:
+
+- `opencode-muse-auth`
+- `hermes-muse-code`
+- `openclaw-muse-code`
+
+## Wire contract
+
+| Item | Value |
+|---|---|
+| `CLIENT_ID` | `1031625952748946` |
+| Device authorization | `https://auth.meta.com/oidc/device/authorization/` |
+| Device token | `https://auth.meta.com/oidc/device/token/` |
+| Key mint | `https://api.meta.ai/muse-code/key` |
+| API version header | `x-api-version: 1.0.0` |
+| Cache fields | `apiKey`, `accountId`, `email` (never the OAuth access token) |
+| Inference base URL | `https://api.meta.ai/v1` |
+
+## Behaviour
+
+- Device flow: request a device code, poll the token endpoint, accept
+  `authorization_pending`, increase the interval on `slow_down`, stop on a
+  terminal error or at `expires_in`.
+- Key mint: exchange the OAuth access token for the account-bound inference
+  key; reject an inactive subscription or a pending payment.
+- Persistence: only the inference key and account identity are stored; the
+  OAuth access token stays in memory.
+- Any change to this contract bumps `AUTH_CONTRACT_VERSION` in the code and
+  requires updating the pinned tests in all three repositories.

package/DISCLAIMER.md

@@ -0,0 +1,62 @@
+# Disclaimer and risk notice
+
+This project is an unofficial, community-built integration. It is not affiliated
+with, endorsed by, or supported by Meta Platforms, Inc. or its affiliates
+("Meta"). "Meta", "Muse", "Muse Code", "Muse Spark" and related names are
+trademarks of Meta.
+
+## Why this notice exists
+
+This plugin signs in with a Meta account that has an active Muse Code
+subscription and uses the subscription-linked credential to send inference
+requests from opencode, a third-party coding client.
+
+Meta's [Meta Model API Terms of Service](https://dev.meta.ai/legal/terms-of-service),
+Section 3.2, states that a credential connected for a Coding Harness
+Subscription "is for use only with the coding harness under your Coding Harness
+Subscription" and "may not be used to access the Services outside the coding
+harness or to circumvent your subscription's usage limits or billing". Meta's
+[Muse Code subscription documentation](https://dev.meta.ai/docs/muse-code/subscriptions)
+likewise states that the subscription credential "is for use with Muse Code
+only".
+
+This project therefore relies on a use that Meta does not document as supported.
+Meta may change, restrict or enforce its terms at any time, and may suspend,
+restrict or terminate accounts, subscriptions or credentials involved. The
+authors cannot prevent, predict or reverse that outcome.
+
+## No warranty, no guarantee
+
+- The integration is provided "as is"; there is no guarantee that it is
+  permitted by Meta's terms, that it will keep working, or that the subscription
+  will remain available.
+- The authors cannot restore an account, subscription, credential or data after
+  Meta takes action, and cannot intervene with Meta on your behalf.
+- This notice is informational and is not legal advice.
+
+## Your responsibility
+
+By installing or using this software you acknowledge that:
+
+1. you are responsible for complying with Meta's terms, including Section 3.2;
+2. you use your own account and credentials and accept the risk of account or
+   subscription action by Meta;
+3. you will not use this software where losing access would be unacceptable, and
+   you will not share credential caches or exported keys;
+4. you will delete cached credentials when you stop using the software.
+
+## Limitation of liability
+
+To the maximum extent permitted by applicable law, the authors and contributors
+are not liable for any loss or damage arising out of or related to this software
+or its use, including account suspension, subscription termination, credential
+revocation, loss of data, or service interruption. Nothing in this notice
+excludes or limits liability that cannot be excluded or limited by applicable
+law. The [MIT License](LICENSE) contains the warranty disclaimer and liability
+limitation that govern the software; this notice does not modify it.
+
+## Clearly supported alternatives
+
+If you need an integration that is unambiguously within Meta's terms, use a Meta
+Model API key billed pay-as-you-go, or drive Muse Code through its official
+`muse serve` session interface.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 TheStreamCode
+Copyright (c) 2026 Michael Gasperini (Mikesoft)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,59 +1,155 @@
 # opencode-muse-auth
 
-Use Meta **Muse Spark** in [opencode](https://opencode.ai) billed to your
-**Muse Code monthly subscription** — no pay-as-you-go API key, no third-party CLI.
+Muse Code subscription sign-in for opencode
+
+[![CI](https://github.com/TheStreamCode/opencode-muse-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/TheStreamCode/opencode-muse-auth/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/opencode-muse-auth)](https://www.npmjs.com/package/opencode-muse-auth)
+
+opencode plugin that registers the **Muse Code subscription** login method for the built-in `meta`
+provider. No API key to copy and no third-party CLI to install. A successful login does not guarantee
+model access: Meta may reject subscription requests from clients other than Muse Code.
+
+> **Unofficial and experimental.** This plugin uses a Muse Code subscription credential from
+> opencode. Meta's terms limit that credential to Muse Code, so this use may not be supported and
+> Meta may suspend or revoke accounts or credentials. Use it at your own risk; the authors cannot
+> recover an account. Read [DISCLAIMER.md](DISCLAIMER.md) before installing.
 
 ## Install
 
+Add the plugin to `opencode.json`; opencode installs it from npm:
+
 ```jsonc
 // opencode.json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-muse-auth"]
+  "plugins": ["opencode-muse-auth"]
 }
 ```
 
-Then run `/connect` in opencode, pick the `meta` provider and the
-*Muse Code subscription* method: it shows a Meta device page URL and a code.
-Enter the code in your browser (your own Meta account) and the login
-completes by itself.
+## Sign in
+
+1. Run `/connect` in opencode.
+2. Pick the `meta` provider and the **Muse Code subscription** method.
+3. Open the printed Meta device page, enter the printed code, and approve the login in your own
+   browser. The login completes by itself.
+4. Select a `muse-*` model exposed by the `meta` provider, for example `meta/muse-spark-1.3`.
+   Meta's subscription restrictions still apply to requests from opencode.
+
+The plugin mints a stable, account-bound inference key and hands it to opencode. The OAuth access
+token from the login flow is kept in memory only and is never written to disk.
+
+## Features
 
-Verified end-to-end against the published package: isolated project with
-only `"plugin": ["opencode-muse-auth"]`, live chat on `meta/muse-spark-1.3`
-billed to subscription.
+- Registers an `auth` hook for the built-in `meta` provider; there is no separate provider id to
+  configure.
+- Runs the Meta device-code exchange (RFC 8628) inside `/connect`, then mints the subscription
+  inference key through the Model API.
+- Routes through the Responses API; the `meta.txt` system prompt applies automatically to `muse-*`
+  model ids.
+- V1 storage: the OpenCode auth store is the primary source, and the loader falls back to the
+  legacy cache only when the store has no key.
+- V2 storage: the credential lives in the OpenCode integration store, and no local cache is
+  written on this path.
+- Never re-mints on its own; re-run `/connect` only after a 401, because the mint endpoint is
+  aggressively rate-limited.
+- Flow parameters are compatible with the published behavior of oh-my-pi (MIT); see [NOTICE](NOTICE)
+  and [AUTH_CONTRACT.md](AUTH_CONTRACT.md).
 
 ## Requirements
 
-- opencode with plugin support
-- A Meta account with an active Muse Code subscription
+- opencode with plugin support, including the v2 plugin module shape accepted by opencode 1.18.29+
+  and 2.x.
+- Node.js 22.6 or newer for development; CI runs Node.js 22 and 24.
+- An active Muse Code subscription on the Meta account used at login.
+
+## Configuration
+
+| Setting | Purpose | Default |
+| --- | --- | --- |
+| `plugins` entry in `opencode.json` | Loads the plugin. | not set |
+| Auth store | Primary credential storage used by the V1 loader. | `~/.local/share/opencode/auth.json` |
+| Legacy cache | Read-only fallback for credentials written by earlier versions. | `~/.config/opencode/muse-code-sub.json` |
+| `/connect` method | Selects Muse Code subscription login for the `meta` provider. | `meta` provider |
+
+## Privacy and security
+
+The inference key is held by opencode: in the V1 auth store or the V2 integration store. The
+legacy cache, when present, stores only `apiKey`, `accountId`, and `email`; the OAuth access token
+is never written to disk. The plugin talks only to `auth.meta.com` for the device login and
+`api.meta.ai` for key minting and inference. See [SECURITY.md](SECURITY.md) for vulnerability
+reporting.
+
+To remove access:
+
+- disconnect the provider or log out in opencode (the store is
+  `~/.local/share/opencode/auth.json`);
+- delete `~/.config/opencode/muse-code-sub.json` if an older version created it;
+- run `muse logout` if you also want to clear the Muse Code CLI session;
+- remove `opencode-muse-auth` from `opencode.json`.
+
+## Troubleshooting
 
-## How it works
+### `/connect` shows no Muse Code subscription method
 
-The plugin registers an `auth` hook for the built-in `meta` provider
-(Routes through the Responses API, `meta.txt` system prompt applies
-automatically to `muse-*` model ids):
+The plugin is not loaded. Check the JSON syntax of `opencode.json`, the plugin name spelling, and
+the package installation, then restart opencode.
 
-- **Login** — Meta device-code exchange (RFC 8628) inside `/connect`, then
-  mints the stable account-bound inference key via the Model API. The key is
-  cached locally (`~/.config/opencode/muse-code-sub.json`, owner-only
-  permissions where supported) and never printed. The cache stores exactly
-  `apiKey`, `accountId`, and `email` — the OAuth access token from the
-  login flow is kept in memory only and never written to disk.
-- **Runtime** — an auth `loader` injects the cached key on every startup.
-  The mint endpoint is aggressively rate-limited, so the plugin never
-  re-mints on its own; re-run `/connect` only if access is revoked (401).
+### Requests fail with 401 or access was revoked
 
-Flow parameters are compatible with the published behavior of oh-my-pi (MIT);
-see [NOTICE](NOTICE).
+A 401 may indicate a rotated or revoked key. Re-run `/connect` once; the plugin never re-mints on
+its own.
+
+### Meta rejects subscription requests from this client
+
+Meta may return a 403 mentioning `client_attestation_denied` or that Muse Code subscriptions cover
+the Muse Code client only. This is a client restriction, not evidence of an expired key. Signing in
+again does not remove the restriction. Use Muse Code for the subscription, or a separate
+pay-as-you-go Meta Model API key for other clients, subject to Meta's terms.
+
+### The login times out or is denied
+
+Approve the printed code in the browser before the flow expires, then retry. A login rejected by
+Meta usually means the account has no active Muse Code subscription.
+
+### A legacy cache file is still present
+
+It is harmless: the V1 loader prefers the OpenCode auth store and reads the cache only when the
+store has no key. Delete the file if you are migrating to V2 storage.
 
 ## Development
 
-```sh
+Requirements: Node.js 22.6 or newer and npm.
+
+```bash
+git clone https://github.com/TheStreamCode/opencode-muse-auth.git
+cd opencode-muse-auth
 npm install
 npm run build
 npm test
 ```
 
+`npm test` builds with `tsc` and runs the TypeScript test suite with the Node test runner. CI runs
+the same gate on Node.js 22 and 24; Node 22 needs 22.6 or newer for test-runner type stripping.
+No Meta account is needed for the test suite.
+
+## Support
+
+Usage questions and workflows belong in GitHub Discussions; reproducible defects belong in GitHub
+Issues using the bug report form. See [SUPPORT.md](SUPPORT.md). Problems in opencode or Meta
+themselves belong to their respective projects.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Pull requests must pass the required CI checks.
+
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [`LICENSE`](LICENSE). The software is provided "as is"; see
+[DISCLAIMER.md](DISCLAIMER.md) for the risk notice and liability terms.
+
+---
+
+Maintained by [Michael Gasperini (Mikesoft)](https://mikesoft.it).
+If this project is useful to you, consider
+[sponsoring its maintenance](https://github.com/sponsors/TheStreamCode).

package/dist/auth.d.ts

@@ -2,6 +2,7 @@ export declare const CLIENT_ID = "1031625952748946";
 export declare const DEVICE_URL = "https://auth.meta.com/oidc/device/authorization/";
 export declare const TOKEN_URL = "https://auth.meta.com/oidc/device/token/";
 export declare const KEY_URL = "https://api.meta.ai/muse-code/key";
+export declare const AUTH_CONTRACT_VERSION = 1;
 export declare const CACHE_PATH: string;
 export interface DeviceAuthorization {
     device_code: string;
@@ -24,6 +25,13 @@ export interface CachedCredential {
     email?: string;
 }
 export declare function readCache(path?: string): Promise<string>;
+/**
+ * Resolve the provider key for the V1 auth loader.
+ *
+ * OpenCode's auth store is authoritative; the local cache is a legacy fallback
+ * for installs created before the host store became the primary source.
+ */
+export declare function resolveLoaderKey(auth: () => Promise<unknown>, readCacheFn?: () => Promise<string>): Promise<string>;
 export declare function writeCache(credentials: MintedCredential, path?: string): Promise<void>;
 export declare function deviceAuthorize(): Promise<DeviceAuthorization>;
 export declare function pollToken(deviceCode: string, intervalS: number, expiresInS: number): Promise<string>;

package/dist/auth.js

@@ -8,6 +8,7 @@ export const CLIENT_ID = "1031625952748946";
 export const DEVICE_URL = "https://auth.meta.com/oidc/device/authorization/";
 export const TOKEN_URL = "https://auth.meta.com/oidc/device/token/";
 export const KEY_URL = "https://api.meta.ai/muse-code/key";
+export const AUTH_CONTRACT_VERSION = 1;
 export const CACHE_PATH = join(homedir(), ".config", "opencode", "muse-code-sub.json");
 const HEADERS = {
     Accept: "application/json",
@@ -25,6 +26,27 @@ export async function readCache(path = CACHE_PATH) {
         return "";
     }
 }
+/**
+ * Resolve the provider key for the V1 auth loader.
+ *
+ * OpenCode's auth store is authoritative; the local cache is a legacy fallback
+ * for installs created before the host store became the primary source.
+ */
+export async function resolveLoaderKey(auth, readCacheFn = readCache) {
+    try {
+        const stored = await auth();
+        if (stored && typeof stored === "object") {
+            const candidate = stored;
+            if (candidate.type === "api" && typeof candidate.key === "string" && candidate.key.trim()) {
+                return candidate.key.trim();
+            }
+        }
+    }
+    catch {
+        // Fall back to the legacy cache below.
+    }
+    return readCacheFn();
+}
 export async function writeCache(credentials, path = CACHE_PATH) {
     // Retention minimization: persist only what inference needs. The OAuth
     // access token has unknown broader scope and nothing reads it back, so it
@@ -79,9 +101,12 @@ export async function pollToken(deviceCode, intervalS, expiresInS) {
     let interval = Math.max(MIN_INTERVAL_S, Number(intervalS) || 5);
     const deadline = Date.now() + Number(expiresInS || 600) * 1000;
     let slowDowns = 0;
+    let transportFailures = 0;
     while (Date.now() < deadline) {
-        // The token endpoint answers HTTP errors (e.g. 400 authorization_pending)
-        // as part of the normal flow: never throw here, classify instead.
+        // The token endpoint answers OAuth errors (e.g. 400 authorization_pending) as part of the
+        // normal flow. A rejected fetch, an unparseable body, or a body carrying neither a token nor an
+        // OAuth error is a transport/proxy blip, not a verdict: count it and keep polling until the
+        // deadline. Only an explicit, terminal OAuth error aborts the device login.
         let body = null;
         try {
             const res = await fetch(TOKEN_URL, {
@@ -104,18 +129,22 @@ export async function pollToken(deviceCode, intervalS, expiresInS) {
         catch {
             body = null;
         }
-        if (body && !body.error) {
-            if (typeof body.access_token !== "string" || !body.access_token) {
-                throw new Error("token response has no access_token");
-            }
+        if (body && typeof body.access_token === "string" && body.access_token) {
             return body.access_token;
         }
         if (body?.error === "slow_down") {
             slowDowns += 1;
             interval = Math.max(MIN_INTERVAL_S, interval + SLOW_DOWN_STEP_S);
         }
-        else if (body?.error !== "authorization_pending") {
-            throw new Error(`login failed: ${body?.error || "unreadable token response"}`);
+        else if (body?.error === "authorization_pending") {
+            // Expected while the user completes approval: keep polling at the current interval.
+        }
+        else if (typeof body?.error === "string" && body.error) {
+            throw new Error(`login failed: ${body.error}`);
+        }
+        else {
+            // Unreadable response: no body, no token, and no OAuth error to classify.
+            transportFailures += 1;
         }
         const remaining = deadline - Date.now();
         if (remaining <= 0)
@@ -124,7 +153,11 @@ export async function pollToken(deviceCode, intervalS, expiresInS) {
         setTimeout(resolve, Math.min(interval, remaining) * 1000);
         await promise;
     }
-    throw new Error(slowDowns ? "login timed out after slow_down responses" : "login timed out waiting for approval");
+    throw new Error(slowDowns
+        ? "login timed out after slow_down responses"
+        : transportFailures > 0
+            ? `login timed out waiting for approval after ${transportFailures} network error${transportFailures === 1 ? "" : "s"}`
+            : "login timed out waiting for approval");
 }
 export async function mintKey(accessToken) {
     const res = await fetch(KEY_URL, {

package/dist/index.js

@@ -1,6 +1,31 @@
 import { Plugin as V2Plugin, Integration } from "@opencode/plugin";
-import { readCache, writeCache, deviceAuthorize, pollToken, mintKey } from "./auth.js";
-const MuseCodeAuth = async () => {
+import { writeCache, deviceAuthorize, pollToken, mintKey, resolveLoaderKey, } from "./auth.js";
+const TEN_YEARS_MS = 10 * 365 * 24 * 60 * 60 * 1000;
+/** Keep diagnostics useful without ever copying a credential into a log line. */
+function describeError(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    return text
+        .replace(/Bearer\s+\S+/gi, "Bearer ***")
+        .replace(/LLM\|[^\s"']+/g, "LLM|***")
+        .slice(0, 300);
+}
+async function logAuthFailure(client, error) {
+    try {
+        const candidate = client;
+        await candidate?.app?.log?.({
+            body: {
+                service: "opencode-muse-auth",
+                level: "error",
+                message: "Muse Code login failed",
+                extra: { error: describeError(error) },
+            },
+        });
+    }
+    catch {
+        // Logging must never break the auth flow.
+    }
+}
+const MuseCodeAuth = async ({ client }) => {
     return {
         auth: {
             provider: "meta",
@@ -22,7 +47,8 @@ const MuseCodeAuth = async () => {
                                     await writeCache(minted);
                                     return { type: "success", key: minted.apiKey };
                                 }
-                                catch {
+                                catch (error) {
+                                    await logAuthFailure(client, error);
                                     return { type: "failed" };
                                 }
                             },
@@ -30,8 +56,8 @@ const MuseCodeAuth = async () => {
                     },
                 },
             ],
-            loader: async () => {
-                const key = await readCache();
+            loader: async (auth) => {
+                const key = await resolveLoaderKey(auth);
                 return key ? { apiKey: key } : {};
             },
         },
@@ -54,16 +80,21 @@ export default {
                         const device = await deviceAuthorize();
                         const url = device.verification_uri_complete || device.verification_uri;
                         const callback = (async () => {
-                            const access = await pollToken(device.device_code, device.interval, device.expires_in);
-                            const minted = await mintKey(access);
-                            return {
-                                type: "oauth",
-                                methodID,
-                                access: minted.apiKey,
-                                refresh: "",
-                                expires: Number.MAX_SAFE_INTEGER,
-                                metadata: { accountId: minted.accountId, ...(minted.email ? { email: minted.email } : {}) },
-                            };
+                            try {
+                                const access = await pollToken(device.device_code, device.interval, device.expires_in);
+                                const minted = await mintKey(access);
+                                return {
+                                    type: "oauth",
+                                    methodID,
+                                    access: minted.apiKey,
+                                    refresh: "",
+                                    expires: Date.now() + TEN_YEARS_MS,
+                                    metadata: { accountId: minted.accountId, ...(minted.email ? { email: minted.email } : {}) },
+                                };
+                            }
+                            catch (error) {
+                                throw new Error(`Muse Code login failed: ${describeError(error)}`);
+                            }
                         })();
                         // The runtime awaits this promise after displaying the device code.
                         // Attach a handler immediately in case the exchange fails first.

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "opencode-muse-auth",
-  "version": "0.3.0",
-  "description": "Muse Spark in opencode billed to the Muse Code monthly subscription (Meta device login, no API key)",
+  "version": "0.4.1",
+  "description": "Unofficial and experimental: Muse Spark in opencode using a Muse Code subscription credential. May conflict with Meta's terms; use at your own risk. See DISCLAIMER.md.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "type": "module",
   "license": "MIT",
-  "author": "TheStreamCode",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/TheStreamCode/opencode-muse-auth.git"
+  "author": {
+    "name": "Michael Gasperini",
+    "url": "https://mikesoft.it"
   },
-  "homepage": "https://github.com/TheStreamCode/opencode-muse-auth#readme",
+  "repository": "github:TheStreamCode/opencode-muse-auth",
+  "homepage": "https://www.npmjs.com/package/opencode-muse-auth",
   "bugs": {
     "url": "https://github.com/TheStreamCode/opencode-muse-auth/issues"
   },
@@ -31,7 +31,9 @@
     "dist",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "DISCLAIMER.md",
+    "AUTH_CONTRACT.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -40,11 +42,11 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "^1.19.0",
-    "@types/node": "^22.20.3",
+    "@opencode-ai/plugin": "^1.19.3",
+    "@types/node": "^26.6.5",
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@opencode/plugin": "^2.0.27"
+    "@opencode/plugin": "^2.0.32"
   }
 }