opencode-muse-auth 0.3.0 → 0.4.0

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/README.md

@@ -3,13 +3,19 @@
 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.
 
+> **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
 
 ```jsonc
 // opencode.json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-muse-auth"]
+  "plugins": ["opencode-muse-auth"]
 }
 ```
 
@@ -19,7 +25,7 @@ Enter the code in your browser (your own Meta account) and the login
 completes by itself.
 
 Verified end-to-end against the published package: isolated project with
-only `"plugin": ["opencode-muse-auth"]`, live chat on `meta/muse-spark-1.3`
+only `"plugins": ["opencode-muse-auth"]`, live chat on `meta/muse-spark-1.3`
 billed to subscription.
 
 ## Requirements
@@ -35,16 +41,32 @@ automatically to `muse-*` model ids):
 
 - **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).
+  never printed and the OAuth access token from the login flow is kept in
+  memory only.
+- **V1 storage** — OpenCode's auth store is the primary source; the auth
+  `loader` falls back to the legacy cache
+  (`~/.config/opencode/muse-code-sub.json`) only when the store has no key.
+  The cache is still written so upgrades keep working.
+- **V2 storage** — the credential lives in OpenCode's integration store; the
+  plugin does not write the local cache on this path.
+- **Runtime** — 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).
 
 Flow parameters are compatible with the published behavior of oh-my-pi (MIT);
-see [NOTICE](NOTICE).
+see [NOTICE](NOTICE) and [AUTH_CONTRACT.md](AUTH_CONTRACT.md).
+
+## Credentials and removal
+
+The inference key is held by OpenCode (V1 auth store or V2 integration store);
+the legacy cache, when present, stores only `apiKey`, `accountId`, and `email`.
+The OAuth access token is never written to disk. To remove access:
+
+- disconnect the provider or log out in OpenCode (this removes the key OpenCode
+  uses; the store is `~/.local/share/opencode/auth.json`);
+- delete `~/.config/opencode/muse-code-sub.json` if it exists from an older
+  version;
+- run `muse logout` if you also want to clear the Muse Code CLI session;
+- remove `opencode-muse-auth` from `opencode.json`.
 
 ## Development
 
@@ -56,4 +78,5 @@ npm test
 
 ## 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.

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

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,7 +1,7 @@
 {
   "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.0",
+  "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",
@@ -31,7 +31,9 @@
     "dist",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "DISCLAIMER.md",
+    "AUTH_CONTRACT.md"
   ],
   "scripts": {
     "build": "tsc",