@gatemux/dsh-gatemux-login 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GateMux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# GateMux Sign-In for DeepSeek Harness
+
+Sign in to the DeepSeek Harness desktop app with your own GateMux account. Model
+requests are then billed to **your** GateMux balance instead of to the
+application's server key.
+
+## What this plugin does
+
+It is a DeepSeek Harness **bundle**. Installing it changes three things about the
+composed profile:
+
+- Adds a GateMux account service that signs you in through GateMux's OAuth 2.0
+  redirect flow (authorization code with PKCE `S256`).
+- Registers a model route, provider id `gatemux-account`, that authenticates every
+  request with your own credential.
+- Turns off the shipped vendor account route (`deepseek-account` and
+  `llm-deepseek-account`) so there is one account provider instead of two.
+
+It also sets the default model to `gatemux/deepseek-v4-flash`. See
+[Changing the default model](#changing-the-default-model) if you would rather
+keep another default.
+
+## Requirements
+
+- DeepSeek Harness desktop app, `0.1.7.x`.
+  The plugin declares `@deepseek-ai/dsh-*` peer dependencies pinned to that line.
+  A different DSH release is rejected at install time; installing anyway needs a
+  version exemption, which risks crashes and data loss.
+- A GateMux account.
+
+No install scripts are run: installation does not execute any build step, and the
+app never asks you to approve package scripts for this plugin.
+
+## Install
+
+In the desktop app:
+
+1. Open **插件** (Plugins) in the left sidebar.
+2. Click **添加插件** (Add plugin).
+3. Enter `@gatemux/dsh-gatemux-login` and click **安装** (Install).
+4. When it reports **已安装** (Installed), click **立即启用** (Enable now).
+5. **Restart the app.** The desktop profile is a startup profile, so the new
+   bundle is composed at launch, not applied live.
+
+The plugin manager writes the dependency and adds the bundle to the profile's
+`dsh.profile.bundles` itself. You do not edit any configuration by hand.
+
+From the CLI, for a non-desktop profile:
+
+```sh
+dsh plugin --profile <name> add @gatemux/dsh-gatemux-login
+```
+
+The `desktop` profile is managed exclusively by the Electron application and
+cannot be installed into from the CLI.
+
+## Sign in
+
+Send a message. Until you are signed in, the GateMux route reports:
+
+```
+ACCOUNT_SIGN_IN_REQUIRED: Sign in with GateMux to use the GateMux model route.
+Model requests are billed to your own GateMux balance.
+```
+
+Sign in from the app's account settings. Authorization opens in your browser and
+returns to the app.
+
+## Models
+
+| Model id | Context | Input |
+|---|---|---|
+| `gatemux/deepseek-v4-flash` | 1,000,000 | text, image |
+| `gatemux/deepseek-v4-pro` | 1,000,000 | text |
+
+Both are served from `https://rest.gatemux.ai/v1`.
+
+## Changing the default model
+
+The bundle sets the default model in its own patch layer. A profile's own
+`cordis.patch.yml` is applied **after** every bundle layer, so it wins. Selecting
+another model in the app writes exactly that override for you; to set it by hand,
+add to `$DSH_HOME/profiles/<name>/cordis.patch.yml`:
+
+```yaml
+- id: agent-default-model
+  name: "@deepseek-ai/dsh-agent-default-model"
+  config:
+    provider: some-other-provider
+    model: some-other-model
+    reasoningEffort: high
+```
+
+A patch `name` is a guard, not a rename: it must match the addressed row's current
+module or the patch is skipped.
+
+## Troubleshooting
+
+| What you see | Meaning |
+|---|---|
+| `ACCOUNT_SIGN_IN_REQUIRED` | No credential yet. Sign in. |
+| `ACCOUNT_TOKEN_INVALID` | The credential was revoked, expired, or suspended. It has been discarded; sign in again. |
+| `ACCOUNT_QUOTA_EXCEEDED` | Your GateMux balance or spend cap is exhausted. Top up. |
+| `ip_not_allowed` (HTTP 403) | Your network is not in the GateMux application's trusted egress IP allowlist. Contact the plugin operator. Re-authorizing will not fix it. |
+| `scope_denied`, `model_not_allowed` (HTTP 403) | The application registration does not permit this request. Contact the plugin operator. |
+| Install refused for peer dependencies | Your DSH version is outside `0.1.7.x`. |
+
+403 errors are reported as authorization faults, not retried: they are
+configuration problems on the application's side.
+
+## Credentials and privacy
+
+Your GateMux credential is stored locally at
+`$DSH_HOME/.credentials.yaml` under the key `gatemux/account`, with file mode
+`0600`. It never leaves your machine except as the `Authorization: Bearer` header
+on requests to `https://rest.gatemux.ai`.
+
+Refresh tokens rotate on every refresh, and the rotated value is persisted
+immediately; a reused rotated refresh token is treated as credential leakage. If
+a token exchange returns `invalid_grant`, that authorization code is voided on the
+server and is not retried.
+
+## License
+
+MIT

package/account.js

@@ -0,0 +1,671 @@
+/**
+ * GateMux OAuth 2.0 account provider.
+ *
+ * Implements the `ctx.deepseekAccount` contract with the GateMux redirect flow
+ * (authorization code + PKCE S256). The user signs in with their own GateMux
+ * account, so model requests are billed to the user's balance rather than to
+ * the application's server key.
+ *
+ * Security invariants enforced here:
+ * - `code_verifier` is generated per attempt, kept in memory, and never placed
+ *   in the authorize URL, the `state`, a log line, or an error message.
+ * - `state` is compared with a constant-time equality check.
+ * - A token exchange that returns `invalid_grant` voids that authorization code
+ *   on the server, so it is never retried with a corrected verifier.
+ * - Refresh tokens rotate on every refresh; the rotated value is persisted
+ *   immediately and refreshes are single-flight, because reusing a rotated
+ *   refresh token is treated as credential leakage.
+ *
+ * @module @gatemux/dsh-gatemux-login/account
+ */
+
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
+import { promises as streamPromises } from 'node:stream'
+
+import { Service } from '@deepseek-ai/cordis'
+import { credentialKey } from '@deepseek-ai/dsh-credentials'
+import {
+  DeepSeekAccount,
+  installAccountTaskCancellation,
+} from '@deepseek-ai/dsh-deepseek-account'
+
+/**
+ * Deployment defaults. Every one of these is overridable through the row's
+ * `config`, so the composition stays the single source of truth and this module
+ * carries no deployment-specific literal that a patch cannot correct.
+ */
+const DEFAULT_ISSUER = 'https://rest.gatemux.ai'
+const DEFAULT_CONSOLE_ORIGIN = 'https://gatemux.ai'
+/** Exact callback path registered for this application; loopback permits any port. */
+const CALLBACK_PATH = '/callback'
+const KEY = credentialKey('gatemux', 'account')
+/** Refresh this long before actual expiry so an in-flight request cannot race it. */
+const REFRESH_MARGIN_MS = 60_000
+const ATTEMPT_TIMEOUT_MS = 600_000
+const REQUEST_TIMEOUT_MS = 30_000
+const DEFAULT_SCOPES = ['models:read', 'responses:create', 'media:create', 'account:read', 'openid', 'email']
+
+/** Local attempt failure taxonomy; the abstract contract renders these through locale copy. */
+class GateMuxAuthError extends Error {
+  /** @param message - diagnostic text without credentials. @param code - stable failure class. */
+  constructor(message, code) {
+    super(message)
+    this.name = 'GateMuxAuthError'
+    this.code = code
+  }
+}
+
+/** Validate the stored grant without trusting its shape. */
+function parseGrant(payload, issuer) {
+  if (typeof payload !== 'object' || payload === null) return null
+  const { version, accessToken, refreshToken, expiresAt } = payload
+  if (version !== 1) return null
+  if (typeof accessToken !== 'string' || accessToken.length === 0) return null
+  if (typeof refreshToken !== 'string' || refreshToken.length === 0) return null
+  if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt)) return null
+  // A grant minted by any other issuer is not one this deployment may use.
+  if (payload.issuer !== issuer) return null
+  return { version: 1, accessToken, refreshToken, expiresAt, issuer }
+}
+
+/** Accept a bare HTTPS origin, rejecting paths, credentials, and non-HTTPS schemes. */
+function originOf(value) {
+  let url
+  try { url = new URL(value) } catch { throw new GateMuxAuthError('origin must be an absolute URL', 'protocol') }
+  if (url.protocol !== 'https:' || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new GateMuxAuthError('origin must be a bare HTTPS origin without a path', 'protocol')
+  }
+  return url.origin
+}
+
+/** Accept a browser-accessible loopback HTTP origin, mirroring the account seam's expectation. */
+function loginOrigin(value) {
+  const explicitPort = /^http:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):([0-9]+)\/?$/i.exec(value)?.[1]
+  if (explicitPort === undefined || Number(explicitPort) === 0) {
+    throw new GateMuxAuthError('callback origin must be loopback HTTP with an explicit port', 'protocol')
+  }
+  return `http://${new URL(value).hostname}:${Number(explicitPort)}`
+}
+
+/**
+ * Extract the RFC 6749 §5.2 error code from a token-endpoint response body.
+ * The token endpoint uses a flat envelope, unlike the nested API envelope.
+ */
+function tokenErrorCode(body) {
+  if (typeof body !== 'object' || body === null) return undefined
+  return typeof body.error === 'string' ? body.error : undefined
+}
+
+/** Extract the machine code from a nested API error envelope. */
+function apiErrorCode(body) {
+  if (typeof body !== 'object' || body === null) return undefined
+  const error = body.error
+  if (typeof error !== 'object' || error === null) return undefined
+  return typeof error.code === 'string' ? error.code : undefined
+}
+
+/** GateMux login state, stored grant, and refresh rotation. */
+export class GateMuxAccount extends DeepSeekAccount {
+  static inject = ['credentials', 'authorization']
+
+  clientId
+  issuer
+  consoleOrigin
+  authorizeEndpoint
+  tokenEndpoint
+  revokeEndpoint
+  accountEndpoint
+  userinfoEndpoint
+  logger
+  scopes
+  attempt
+  listeners = new Set()
+  detailsLifetime = new AbortController()
+  lastProfile
+  refreshInFlight
+  removing
+  closed = false
+
+  /**
+   * @param ctx - Host with the credentials and authorization services.
+   * @param config - application identity and the granted scope set.
+   */
+  constructor(ctx, config = {}) {
+    super(ctx)
+    installAccountTaskCancellation(ctx)
+    const clientId = config.clientId
+    if (typeof clientId !== 'string' || clientId.length === 0) {
+      throw new GateMuxAuthError('clientId is required', 'protocol')
+    }
+    this.clientId = clientId
+    // `rest.gatemux.ai` serves both the API and the OAuth endpoints; the console
+    // is a separate origin used only for links the user opens.
+    const issuer = originOf(config.authorizeOrigin ?? DEFAULT_ISSUER)
+    this.issuer = issuer
+    this.consoleOrigin = originOf(config.consoleOrigin ?? DEFAULT_CONSOLE_ORIGIN)
+    this.authorizeEndpoint = `${issuer}/v1/oauth/authorize`
+    this.tokenEndpoint = `${issuer}/v1/oauth/token`
+    this.revokeEndpoint = `${issuer}/v1/oauth/revoke`
+    this.accountEndpoint = `${issuer}/v1/account/me`
+    this.userinfoEndpoint = `${issuer}/v1/oauth/userinfo`
+    this.logger = ctx.logger('gatemux-account')
+    this.scopes = Array.isArray(config.scopes) && config.scopes.length > 0 ? [...config.scopes] : DEFAULT_SCOPES
+    ctx.authorization.registerFlow({
+      key: KEY,
+      label: 'GateMux',
+      methods: [{ id: 'browser', label: 'GateMux' }],
+      run: (session) => {
+        const attempt = this.attempt
+        if (attempt === undefined) return Promise.reject(new GateMuxAuthError('no attempt', 'protocol'))
+        attempt.running = this.run(session, attempt)
+        return attempt.running
+      },
+    })
+    ctx.on('credentials/record-updated', (key) => {
+      if (key !== KEY) return
+      this.invalidateDetails()
+      this.changed()
+    })
+    ctx.effect(() => async () => {
+      this.closed = true
+      this.invalidateDetails()
+      const active = this.attempt
+      if (active !== undefined) {
+        if (active.view.phase !== 'committing') active.controller.abort()
+        await active.done
+      }
+      await this.removing
+      this.changed()
+    }, 'gatemux-account: active attempt lifetime')
+  }
+
+  /** Discard a stored grant issued by another environment. */
+  async [Service.init]() {
+    const record = await this.ctx.credentials.readRecord(KEY)
+    if (record === undefined) return
+    const grant = record.kind === 'grant' ? parseGrant(record.payload, this.issuer) : null
+    if (grant !== null) return
+    await this.ctx.credentials.deleteRecord(KEY)
+    this.logger.warn('stored grant discarded', { reason: 'unreadable-or-foreign-issuer' })
+  }
+
+  async getState() {
+    const record = await this.ctx.credentials.readRecord(KEY)
+    if (record !== undefined && (record.kind !== 'grant' || parseGrant(record.payload, this.issuer) === null)) {
+      throw new GateMuxAuthError('stored grant is unreadable', 'storage')
+    }
+    const attempt = this.attempt?.view ?? null
+    return {
+      status: record === undefined ? 'signed-out' : 'credential-stored',
+      attempt: record === undefined && attempt?.phase === 'succeeded' ? null : attempt,
+      links: {
+        usageUrl: `${this.consoleOrigin}/app/usage`,
+        topUpUrl: `${this.consoleOrigin}/app/billing`,
+      },
+    }
+  }
+
+  async getProfile(client) {
+    const lifetime = this.detailsLifetime
+    const grant = await this.readGrant(lifetime)
+    if (grant === null || lifetime.signal.aborted) return null
+    const identity = await this.readIdentity(grant, lifetime, client)
+    if (this.detailsLifetime !== lifetime) return null
+    if (identity === null) return { status: 'failed' }
+    this.cacheProfile(grant.accessToken, identity)
+    return { status: 'ready', value: identity }
+  }
+
+  /**
+   * Wallet balances require the `billing:read` scope, which this application is
+   * not granted. A response without a usable wallet is reported as a failed
+   * balance rather than an invented zero.
+   */
+  async getBalance(client) {
+    const lifetime = this.detailsLifetime
+    const grant = await this.readGrant(lifetime)
+    if (grant === null || lifetime.signal.aborted) return null
+    const body = await this.callApi(this.accountEndpoint, grant, lifetime, client)
+    if (this.detailsLifetime !== lifetime) return null
+    if (body === null) return { status: 'failed' }
+    const wallet = body.wallet
+    if (typeof wallet !== 'object' || wallet === null) return { status: 'failed' }
+    const { currency, balance } = wallet
+    if (currency !== 'CNY' && currency !== 'USD') return { status: 'failed' }
+    if (typeof balance !== 'string') return { status: 'failed' }
+    return { status: 'ready', value: [{ currency, balance }], bonusWallets: [] }
+  }
+
+  /** GateMux grants no campaign bonuses; the contract reports an empty batch. */
+  async getUnnotifiedBonuses(client) {
+    const lifetime = this.detailsLifetime
+    const grant = await this.readGrant(lifetime)
+    if (grant === null || lifetime.signal.aborted) return null
+    const profile = this.lastProfile?.token === grant.accessToken ? this.lastProfile.profile : null
+    const accountId = profile?.id ?? (await this.getProfile(client))?.value?.id ?? null
+    if (accountId === null) return null
+    return { accountId, bonuses: [] }
+  }
+
+  /** No bonus can be acknowledged because none is ever granted. */
+  async ackBonusNotified() {
+    return false
+  }
+
+  async startSignIn(_client, callbackOrigin, loginSource) {
+    if (this.removing !== undefined) await this.removing
+    const origin = loginOrigin(callbackOrigin)
+    if (this.closed) throw new GateMuxAuthError('provider is closed', 'protocol')
+    const active = this.attempt
+    if (active !== undefined && ['initializing', 'waiting-browser', 'exchanging', 'committing'].includes(active.view.phase)) {
+      return this.getState()
+    }
+    const attempt = {
+      origin,
+      loginSource,
+      view: { id: randomUUID(), phase: 'initializing' },
+      controller: new AbortController(),
+      done: Promise.resolve(),
+      running: Promise.resolve(),
+    }
+    this.attempt = attempt
+    attempt.done = this.ctx.authorization.begin({
+      key: KEY,
+      signal: attempt.controller.signal,
+      interaction: { notify: () => undefined, prompt: () => Promise.reject(new GateMuxAuthError('no prompt', 'protocol')) },
+    }).then((outcome) => {
+      this.update(attempt, { phase: outcome.status === 'authorized' ? 'succeeded' : 'cancelled' })
+      if (outcome.status === 'authorized' && attempt.completionUrl !== undefined) {
+        attempt.callback?.writeHead(302, { location: attempt.completionUrl, 'cache-control': 'no-store' }).end()
+      } else {
+        attempt.callback?.writeHead(204, { 'cache-control': 'no-store' }).end()
+      }
+    }).catch((error) => {
+      const code = error instanceof GateMuxAuthError ? error.code : 'protocol'
+      // Anything that is not a GateMuxAuthError is a defect rather than a rejected
+      // attempt, so its message is kept: otherwise every such failure reads as a bare
+      // `protocol` and the exchange that rejected it cannot be told from the seam.
+      const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error)
+      this.logger.warn('sign-in failed', { errorCode: code, detail })
+      this.update(attempt, { phase: code === 'expired' ? 'expired' : 'failed', errorCode: code })
+      this.finishFailedCallback(attempt)
+    }).then(async () => {
+      await attempt.running.catch(() => undefined)
+      if (attempt.callback !== undefined) {
+        await streamPromises.finished(attempt.callback, { cleanup: true }).catch(() => undefined)
+      }
+      await attempt.disposeCallback?.()
+    })
+    this.changed()
+    return this.getState()
+  }
+
+  async cancelSignIn(id) {
+    const attempt = this.attempt
+    if (attempt?.view.id === id) {
+      if (attempt.view.phase !== 'committing') {
+        attempt.controller.abort()
+        this.ctx.authorization.cancel(KEY)
+      }
+      await attempt.done
+    }
+    return this.getState()
+  }
+
+  signOut(client) {
+    this.removing ??= (async () => {
+      if (this.closed) throw new GateMuxAuthError('provider is closed', 'protocol')
+      if (this.attempt !== undefined) await this.cancelSignIn(this.attempt.view.id)
+      const record = await this.ctx.credentials.readRecord(KEY)
+      if (record !== undefined) {
+        const grant = record.kind === 'grant' ? parseGrant(record.payload, this.issuer) : null
+        if (grant === null) throw new GateMuxAuthError('stored grant is unreadable', 'storage')
+        await this.ctx.credentials.deleteRecord(KEY)
+        // Revoking the refresh token cascades to every access token it issued.
+        this.revoke(grant.refreshToken)
+      }
+      this.attempt = undefined
+      this.ctx.emit('deepseek-account/signed-out')
+      this.changed()
+      return this.getState()
+    })().finally(() => { this.removing = undefined })
+    return this.removing
+  }
+
+  async *watch(signal) {
+    let dirty = true
+    let wake
+    const changed = () => { dirty = true; wake?.() }
+    this.listeners.add(changed)
+    signal.addEventListener('abort', changed, { once: true })
+    try {
+      while (!this.closed && !signal.aborted) {
+        if (dirty) { dirty = false; yield await this.getState(); continue }
+        await new Promise((resolve) => { wake = resolve })
+      }
+    } finally {
+      this.listeners.delete(changed)
+      signal.removeEventListener('abort', changed)
+    }
+  }
+
+  /** Resolve a token only for the GateMux REST origin, refreshing it when stale. */
+  async resolveToken(url) {
+    if (this.closed || this.removing !== undefined) return undefined
+    let destination
+    try { destination = new URL(url) } catch { return undefined }
+    if (destination.origin !== this.issuer || destination.username || destination.password) return undefined
+    const grant = await this.freshGrant()
+    return grant?.accessToken
+  }
+
+  /** Remove a rejected token only while it still matches the stored credential. */
+  async rejectToken(token) {
+    const lifetime = this.detailsLifetime
+    const grant = await this.readGrant(lifetime)
+    if (grant?.accessToken !== token) return
+    await this.expireCredential(token, lifetime)
+  }
+
+  /** GateMux embeds no console documents, so there is no host-only session to publish. */
+  async getPlatformSession() {
+    return null
+  }
+
+  /**
+   * Run one authorization attempt: PKCE, browser callback, code exchange, commit.
+   * @param session - the attempt's cancellation signal and commit channel.
+   * @param attempt - the attempt record whose phase drives the UI.
+   */
+  async run(session, attempt) {
+    const webServer = this.ctx.get('webServer')
+    if (webServer === undefined) throw new GateMuxAuthError('web server is unavailable', 'protocol')
+    const verifier = randomBytes(32).toString('base64url')
+    const state = randomBytes(32).toString('base64url')
+    const challenge = createHash('sha256').update(verifier).digest('base64url')
+    const redirectUri = `${attempt.origin}${CALLBACK_PATH}`
+    const code = Promise.withResolvers()
+    // A callback may arrive before initialization settles; observe the rejection immediately.
+    void code.promise.catch(() => undefined)
+    const deadline = new AbortController()
+    const signal = AbortSignal.any([session.signal, deadline.signal])
+    // Published to the client and re-checked after the exchange, so it has to be
+    // the same instant the deadline aborts at rather than a second clock.
+    const expiresAt = Date.now() + ATTEMPT_TIMEOUT_MS
+    const timer = setTimeout(() =>{ deadline.abort() }, ATTEMPT_TIMEOUT_MS)
+    const abort = () => { code.reject(new GateMuxAuthError('attempt expired', 'expired')) }
+    signal.addEventListener('abort', abort, { once: true })
+    try {
+      attempt.disposeCallback = this.ctx.effect(() => webServer.register({
+        kind: 'exact', path: CALLBACK_PATH, handler: (req, res) => {
+          let url
+          try { url = new URL(req.url ?? '/', 'http://127.0.0.1') }
+          catch { res.writeHead(400, { 'cache-control': 'no-store' }).end(); return }
+          const receivedCode = url.searchParams.get('code')
+          const receivedState = url.searchParams.get('state') ?? ''
+          const validState = Buffer.byteLength(receivedState) === Buffer.byteLength(state)
+            && timingSafeEqual(Buffer.from(receivedState), Buffer.from(state))
+          if (req.method !== 'GET' || url.pathname !== CALLBACK_PATH || !validState || !receivedCode
+            || url.searchParams.getAll('state').length !== 1 || url.searchParams.getAll('code').length !== 1) {
+            res.writeHead(400, { 'cache-control': 'no-store' }).end(); return
+          }
+          if (signal.aborted || attempt.callback !== undefined || attempt.view.phase !== 'waiting-browser') {
+            res.writeHead(410, { 'cache-control': 'no-store' }).end(); return
+          }
+          attempt.callback = res
+          code.resolve(receivedCode)
+        },
+      }), 'gatemux-account: browser callback')
+      signal.throwIfAborted()
+      const authorizeUrl = new URL(this.authorizeEndpoint)
+      authorizeUrl.searchParams.set('response_type', 'code')
+      authorizeUrl.searchParams.set('client_id', this.clientId)
+      authorizeUrl.searchParams.set('redirect_uri', redirectUri)
+      authorizeUrl.searchParams.set('state', state)
+      authorizeUrl.searchParams.set('scope', this.scopes.join(' '))
+      authorizeUrl.searchParams.set('code_challenge', challenge)
+      authorizeUrl.searchParams.set('code_challenge_method', 'S256')
+      this.update(attempt, {
+        phase: 'waiting-browser',
+        authorizeUrl: authorizeUrl.href,
+        expiresAt,
+      })
+      const receivedCode = await code.promise
+      signal.throwIfAborted()
+      this.update(attempt, { phase: 'exchanging' })
+      const grant = await this.exchange(receivedCode, verifier, redirectUri, signal)
+      if (Date.now() >= expiresAt) throw new GateMuxAuthError('attempt expired', 'expired')
+      signal.throwIfAborted()
+      this.update(attempt, { phase: 'committing' })
+      try {
+        await session.commit({ kind: 'grant', payload: grant })
+      } catch {
+        throw new GateMuxAuthError('stored grant could not be written', 'storage')
+      }
+    } catch (error) {
+      if (deadline.signal.aborted) throw new GateMuxAuthError('attempt expired', 'expired')
+      throw error
+    } finally {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', abort)
+      // begin() settles the browser response and removes only this attempt's route.
+    }
+  }
+
+  /**
+   * Exchange an authorization code for tokens.
+   *
+   * `invalid_grant` is terminal: the server voids the code when the verifier
+   * does not match, so retrying the same code can never succeed.
+   */
+  async exchange(code, verifier, redirectUri, signal) {
+    const response = await this.postToken({
+      grant_type: 'authorization_code',
+      code,
+      code_verifier: verifier,
+      client_id: this.clientId,
+      redirect_uri: redirectUri,
+    }, signal)
+    if (!response.ok) {
+      // RFC 6749 §5.2 flat body. A reused `code`, a `code_verifier` that does not match
+      // the challenge, and a `redirect_uri` that differs from the authorize request all
+      // arrive as `invalid_grant`, so the server's own description is the only thing
+      // that tells them apart — discarding it leaves nothing to act on.
+      const code = tokenErrorCode(response.body)
+      const description = typeof response.body?.error_description === 'string' ? response.body.error_description : undefined
+      this.logger.warn('authorization code rejected', { status: response.status, errorCode: code ?? 'unknown', description })
+      throw new GateMuxAuthError(`authorization code rejected (${response.status} ${code ?? 'unknown'})`, 'protocol')
+    }
+    return this.grantFrom(response.body)
+  }
+
+  /** Read the newest grant, refreshing it when it is close to expiry. */
+  async freshGrant() {
+    const grant = await this.readGrant(this.detailsLifetime)
+    if (grant === null) return null
+    if (grant.expiresAt - Date.now() > REFRESH_MARGIN_MS) return grant
+    this.refreshInFlight ??= this.rotate().finally(() => { this.refreshInFlight = undefined })
+    try {
+      return await this.refreshInFlight
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Rotate the refresh token exactly once at a time.
+   *
+   * Refreshes are serialized because GateMux voids the whole authorization
+   * chain when a rotated refresh token reappears after a grace period.
+   */
+  async rotate() {
+    const lifetime = this.detailsLifetime
+    const grant = await this.readGrant(lifetime)
+    if (grant === null) throw new GateMuxAuthError('signed out', 'expired')
+    const response = await this.postToken({
+      grant_type: 'refresh_token',
+      refresh_token: grant.refreshToken,
+      client_id: this.clientId,
+    }, lifetime.signal)
+    if (!response.ok) {
+      const code = tokenErrorCode(response.body)
+      // An unknown or expired refresh token means the authorization is gone.
+      this.logger.warn('refresh rejected', { errorCode: code ?? 'unknown' })
+      await this.expireCredential(grant.accessToken, lifetime)
+      throw new GateMuxAuthError('refresh token rejected', 'expired')
+    }
+    const next = this.grantFrom(response.body)
+    // Persist the rotated token before any other request can read the old one.
+    await this.ctx.credentials.modifyRecord(KEY, (current) => Promise.resolve(
+      current !== undefined && parseGrant(current.payload, this.issuer) !== null
+        ? { kind: 'grant', payload: next }
+        : undefined,
+    ))
+    return next
+  }
+
+  /** Build a validated grant from a token-endpoint response. */
+  grantFrom(body) {
+    if (typeof body !== 'object' || body === null) throw new GateMuxAuthError('token response was not an object', 'protocol')
+    const { access_token: accessToken, refresh_token: refreshToken, expires_in: expiresIn } = body
+    if (typeof accessToken !== 'string' || accessToken.length === 0) throw new GateMuxAuthError('token response carried no access token', 'protocol')
+    if (typeof refreshToken !== 'string' || refreshToken.length === 0) throw new GateMuxAuthError('token response carried no refresh token', 'protocol')
+    const seconds = typeof expiresIn === 'number' && Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 3600
+    return { version: 1, accessToken, refreshToken, expiresAt: Date.now() + seconds * 1000, issuer: this.issuer }
+  }
+
+  /** Post one token-endpoint request and decode its RFC 6749 §5.2 envelope. */
+  async postToken(fields, signal) {
+    const response = await fetch(this.tokenEndpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify(fields),
+      signal: AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]),
+    })
+    let body
+    try { body = await response.json() } catch { body = undefined }
+    return { ok: response.ok, status: response.status, body }
+  }
+
+  /**
+   * Call one account endpoint, expiring the credential on an authenticated rejection.
+   * @returns the decoded body, or null when the credential was rejected.
+   */
+  async callApi(url, grant, lifetime, _client) {
+    let response
+    try {
+      response = await fetch(url, {
+        headers: { authorization: `Bearer ${grant.accessToken}`, accept: 'application/json' },
+        signal: AbortSignal.any([lifetime.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]),
+      })
+    } catch {
+      return null
+    }
+    let body
+    try { body = await response.json() } catch { body = undefined }
+    if (response.ok) return body
+    // 401 credential_invalid means re-authorization; other codes are configuration problems.
+    if (response.status === 401 || apiErrorCode(body) === 'credential_invalid') {
+      if (this.detailsLifetime === lifetime) await this.expireCredential(grant.accessToken, lifetime)
+      return null
+    }
+    return null
+  }
+
+  /** Read the profile identity, enriching it with the OpenID email when available. */
+  async readIdentity(grant, lifetime, client) {
+    const me = await this.callApi(this.accountEndpoint, grant, lifetime, client)
+    if (me === null || typeof me !== 'object') return null
+    const accountId = typeof me.account_id === 'string' && me.account_id.length > 0 ? me.account_id : null
+    const masked = typeof me.email_masked === 'string' && me.email_masked.length > 0 ? me.email_masked : null
+    let contact = masked
+    if (contact === null) {
+      const info = await this.callApi(this.userinfoEndpoint, grant, lifetime, client)
+      if (typeof info === 'object' && info !== null && typeof info.email === 'string' && info.email.length > 0) {
+        contact = info.email
+      }
+    }
+    const id = accountId ?? (typeof me.user_id === 'string' && me.user_id.length > 0 ? me.user_id : null)
+    if (id === null && contact === null) return null
+    return { id, name: contact, contact, avatarUrl: null }
+  }
+
+  cacheProfile(token, profile) {
+    const previous = this.lastProfile?.profile.id ?? null
+    this.lastProfile = { token, profile }
+    if (previous !== profile.id) this.changed()
+  }
+
+  async readGrant(lifetime) {
+    if (this.closed) return null
+    const record = await this.ctx.credentials.readRecord(KEY)
+    if (record === undefined || lifetime.signal.aborted) return null
+    if (record.kind !== 'grant') throw new GateMuxAuthError('stored record is not a grant', 'storage')
+    const grant = parseGrant(record.payload, this.issuer)
+    if (grant === null) throw new GateMuxAuthError('stored grant is unreadable', 'storage')
+    return grant
+  }
+
+  /** Delete the credential and notify consumers that the session ended. */
+  async expireCredential(token, lifetime) {
+    this.removing ??= (async () => {
+      if (this.attempt !== undefined) await this.cancelSignIn(this.attempt.view.id)
+      const record = await this.ctx.credentials.readRecord(KEY)
+      if (this.closed || this.detailsLifetime !== lifetime || record?.kind !== 'grant') return this.getState()
+      const current = parseGrant(record.payload, this.issuer)
+      if (current === null || current.accessToken !== token) return this.getState()
+      await this.ctx.credentials.deleteRecord(KEY)
+      this.ctx.emit('deepseek-account/session-expired')
+      this.attempt = undefined
+      this.ctx.emit('deepseek-account/signed-out')
+      this.changed()
+      return this.getState()
+    })().finally(() => { this.removing = undefined })
+    await this.removing
+  }
+
+  /** Revoke a refresh token, cascading to its access tokens; failures are not fatal. */
+  revoke(refreshToken) {
+    if (this.closed) return
+    void fetch(this.revokeEndpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify({ token: refreshToken }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }).then(() => undefined, () => undefined)
+  }
+
+  invalidateDetails() {
+    this.lastProfile = undefined
+    this.detailsLifetime.abort()
+    this.detailsLifetime = new AbortController()
+  }
+
+  changed() { for (const listener of this.listeners) listener() }
+
+  update(attempt, value) {
+    const { authorizeUrl: _url, ...rest } = attempt.view
+    attempt.view = { ...rest, ...value }
+    this.changed()
+  }
+
+
+  /** Return the browser to the application after a failed exchange. */
+  finishFailedCallback(attempt) {
+    if (attempt.loginSource === 'web') {
+      const nonce = randomBytes(16).toString('base64url')
+      const message = 'Sign-in failed. Close this tab and try again in the original tab.'
+      attempt.callback?.writeHead(200, {
+        'content-type': 'text/html; charset=utf-8',
+        'cache-control': 'no-store',
+        'content-security-policy': `default-src 'none'; frame-ancestors 'none'`,
+        'referrer-policy': 'no-referrer',
+      }).end(`<!doctype html><html lang="en"><meta charset="utf-8"><title>${message}</title>`
+        + `<body><p>${message}</p></body></html>`)
+    } else {
+      attempt.callback?.writeHead(204, { 'cache-control': 'no-store' }).end()
+    }
+  }
+}
+
+export default GateMuxAccount

package/cordis.patch.yml

@@ -0,0 +1,96 @@
+# GateMux Sign-In for DeepSeek Harness.
+#
+# Composition shape.
+#
+# A patch's `name` is a GUARD, not a rename: `applyEntryPatches` skips any patch
+# whose `name` differs from the addressed row's current module, warning
+# "name mismatch ... skipping". A shipped row's module therefore can never be
+# swapped by a patch, and only a whole new row can be inserted. Two consequences
+# shape this file:
+#
+#   * the GateMux account service is added as its own row rather than by
+#     re-pointing `deepseek-account`, whose module would ignore the rename;
+#   * `ctx.deepseekAccount` is a single service slot — a second provider throws
+#     "service has been registered at ..." — so the shipped row is turned off
+#     instead, which is what frees the slot for the GateMux implementation.
+#
+# `disabled: true` on a shipped row is a normal patch override and persists
+# across boots, because the bundle layers are re-read from these packages on
+# every launch.
+#
+# Every row `name` below carries this package's own name. Renaming the package
+# in package.json without mirroring it here leaves the rows unresolvable, and
+# the load reports "failed to import" rather than anything naming the rename.
+
+- id: deepseek-account
+  disabled: true
+
+- id: llm-deepseek-account
+  disabled: true
+
+- insert:
+    - id: gatemux-account
+      name: '@gatemux/dsh-gatemux-login/account'
+      config:
+        clientId: app_cbd5c3e0ac4469cf
+        authorizeOrigin: https://rest.gatemux.ai
+        consoleOrigin: https://gatemux.ai
+        # Exactly the scopes granted to this application in the GateMux portal.
+        # `responses:create` gates /v1/chat/completions, /v1/messages,
+        # /v1/responses, /v1/embeddings and /v1/rerank; it is the only paid LLM
+        # scope here, and authorization returns invalid_scope without it.
+        scopes:
+          - models:read
+          - responses:create
+          - media:create
+          - account:read
+          - openid
+          - email
+
+    # The user-funded GateMux route. Its provider id is `gatemux-account`, not
+    # `gatemux`: the profile's `llm-pi-ai` row already owns the `gatemux` route
+    # with the application's own server key, and the LLM registry throws
+    # DUPLICATE_ADAPTER when one route is registered twice.
+    - id: gatemux-messages
+      name: '@gatemux/dsh-gatemux-login/llm'
+      config:
+        baseURL: https://rest.gatemux.ai/v1
+        maxTokens: 8192
+        # GateMux answers both `budget_exceeded` (a spend cap) and
+        # `app_rate_limited` (a transient limit) with HTTP 429, and the upstream
+        # classifier folds both into RATE_LIMIT, so retries are kept low: an
+        # exhausted budget must fail fast for the user to act on rather than be
+        # retried as though it were transient.
+        retryPolicy:
+          mode: normal
+          maxRetries: 3
+          retryableCodes:
+            - RATE_LIMIT
+            - SERVER
+            - TIMEOUT
+            - TRANSPORT
+            - EMPTY_RESPONSE
+        models:
+          - id: gatemux/deepseek-v4-flash
+            name: DeepSeek V4 Flash (GateMux)
+            description: GateMux-routed DeepSeek V4 Flash; vision, tools and reasoning.
+            contextWindow: 1000000
+            inputModalities:
+              - text
+              - image
+          - id: gatemux/deepseek-v4-pro
+            name: DeepSeek V4 Pro (GateMux)
+            description: GateMux-routed DeepSeek V4 Pro; tools and reasoning.
+            contextWindow: 1000000
+            inputModalities:
+              - text
+
+# Point the default model at the user-funded route, so installing this bundle is
+# enough to start using it. A profile's own cordis.patch.yml is applied after
+# every bundle layer, so a user who prefers another default still overrides this.
+- id: agent-default-model
+  name: '@deepseek-ai/dsh-agent-default-model'
+  config:
+    provider: gatemux-account
+    model: gatemux/deepseek-v4-flash
+    reasoningEffort: high

package/llm.js

@@ -0,0 +1,103 @@
+/**
+ * GateMux model route authenticated by the signed-in user's OAuth credential.
+ *
+ * Reuses the DeepSeek Messages adapter because GateMux's `/v1/messages` speaks
+ * the Anthropic protocol verbatim, including DeepSeek's proprietary `thinking`
+ * and `output_config` request fields. Only authentication differs.
+ *
+ * The provider id is deliberately NOT `gatemux`: the profile's `llm-pi-ai` row
+ * already claims that route with the application's server key, and claiming it
+ * twice would throw `DUPLICATE_ADAPTER` and break plugin loading.
+ *
+ * Endpoint, model catalog, and retry policy come from this entry's `config` in
+ * `cordis.patch.yml`, so the composition remains the single source of truth for
+ * deployment choices.
+ *
+ * @module @gatemux/dsh-gatemux-login/llm
+ */
+
+import { ACCOUNT_QUOTA_EXCEEDED_CODE, LlmError, QUOTA_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm'
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
+import { Config, catalogModelInfo, plainOptions, registerDeepSeekProvider, resolveAdapterOptions } from '@deepseek-ai/dsh-llm-deepseek'
+
+export { Config }
+
+/** Route owned by this plugin; distinct from the pi-ai `gatemux` route. */
+export const PROVIDER = 'gatemux-account'
+export const name = 'gatemux-account'
+export const inject = ['llm']
+
+/**
+ * Register the GateMux account-authenticated provider route.
+ * @param ctx - Host context with the LLM registry injected.
+ * @param config - this entry's Messages protocol configuration.
+ */
+export function apply(ctx, config) {
+  const logger = ctx.logger('gatemux-account')
+  const options = () => resolveAdapterOptions(plainOptions(config), launchEnvironmentOf(ctx))
+  // Validate the composed configuration now so a misconfiguration fails loudly at load.
+  options()
+
+  const resolveAuth = async (connection) => {
+    const account = ctx.get('deepseekAccount')
+    const token = await account?.resolveToken(connection.baseURL)
+    if (token === undefined) {
+      throw new LlmError(
+        'Sign in with GateMux to use the GateMux model route. Model requests are billed to your own GateMux balance.',
+        'ACCOUNT_SIGN_IN_REQUIRED',
+      )
+    }
+    return {
+      // GateMux accepts `Authorization: Bearer`; it rejects the DeepSeek-only `x-dsh-auth-token` header.
+      headers: { authorization: `Bearer ${token}` },
+      onRequestError: async (error) => {
+        if (!(error instanceof LlmError)) return error
+        const status = error.failure.status
+        // 402 insufficient_balance and an exhausted quota both mean the user must top up.
+        if (error.code === QUOTA_EXCEEDED_CODE) {
+          return new LlmError(error.message, ACCOUNT_QUOTA_EXCEEDED_CODE, { ...error.failure, cause: error })
+        }
+        // 403 scope_denied / model_not_allowed / ip_not_allowed stay AUTH: they are
+        // configuration faults that re-authorizing the same way would not fix.
+        if (status !== 401) return error
+        // 401 credential_invalid: the credential is revoked, expired, or suspended.
+        // Re-authorization is required, so the stored credential is dropped.
+        const rejected = new LlmError(error.message, 'ACCOUNT_TOKEN_INVALID', { ...error.failure, cause: error })
+        try {
+          await account?.rejectToken(token)
+        } catch (failure) {
+          logger.warn('credential removal after rejection failed', failure)
+        }
+        return rejected
+      },
+    }
+  }
+
+  ctx.llm.registerConfigurableProviders([
+    { provider: PROVIDER, displayName: 'GateMux Account', settingsNs: ctx.fiber.entry?.options.id ?? name, settingsPath: [] },
+  ])
+
+  registerDeepSeekProvider(ctx, PROVIDER, {
+    options,
+    resolveAuth,
+    providerName: 'GateMux Account',
+    discoverModels: async (provider) => {
+      const connection = options()
+      try {
+        await resolveAuth(connection)
+      } catch (error) {
+        // With no signed-in user the route advertises nothing rather than failing discovery.
+        if (error instanceof LlmError && error.code === 'ACCOUNT_SIGN_IN_REQUIRED') return []
+        throw error
+      }
+      return connection.models.map((model) => catalogModelInfo(provider, model))
+    },
+  })
+}
+
+// The loader normalizes a module with `exports.default ?? exports` and then reads
+// `inject` and `Config` off that value, so named exports beside a default are
+// discarded. A bare `apply` default therefore has no `inject` and `ctx.llm` throws
+// "cannot get property \"llm\" without inject"; the plugin object has to be the
+// default export itself.
+export default { name, inject, Config, apply }

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@gatemux/dsh-gatemux-login",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Sign in with GateMux for DeepSeek Harness: users pay from their own GateMux balance.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "files": [
+    "account.js",
+    "llm.js",
+    "cordis.patch.yml"
+  ],
+  "exports": {
+    "./account": "./account.js",
+    "./llm": "./llm.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "meta": {
+    "title": "GateMux Sign-In",
+    "description": "Signs in with GateMux and bills model requests to the user's own GateMux balance."
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-authorization": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-credentials": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-deepseek-account": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.1.7-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-authorization": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-credentials": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-deepseek-account": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.1.7-rc.2"
+  }
+}