@plime-inc/cli 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# PLIME CLI
+
+Node.js 22.12以降。`plime login` でブラウザを開き、PLIMEアカウントで認証します。
+
+```sh
+npm install -g @plime-inc/cli
+plime login
+plime whoami
+plime logout
+```
+
+開発中はworkspace rootから `node packages/cli/plime/bin/plime.js login` で実行できます。パッケージ単体でも動作し、ビルドは不要です。
+
+| 操作 | 説明 |
+| --- | --- |
+| `plime login` | ブラウザでログインし、CLIへのアクセスを許可 |
+| `plime login --no-browser` | URLだけ表示。CLIと同じ端末のブラウザで開く |
+| `plime whoami` | JWT署名・issuer・audience・scopeを検証してユーザーIDを表示。期限が近いtokenは自動更新 |
+| `plime whoami --json` | ユーザーID、issuer、resource、scopes、有効期限をJSON出力 |
+| `plime logout` | refresh tokenをIDPで失効させ、端末の認証情報を削除 |
+| `plime logout --local` | オフライン時などに端末の認証情報だけを削除。IDPでは失効しない |
+| `--dev` | ローカルIDPを使用。本番とは別に保存 |
+
+標準出力は結果、URLやエラーは標準エラーへ出します。token自体を表示するコマンドはありません。`whoami`は氏名・メールアドレスを要求せず、現在許可されたscopeのユーザーIDを表示します。未ログイン・拒否・通信失敗は終了コード1、中断は130です。
+
+認証情報は `$XDG_CONFIG_HOME/plime/<environment>/session.json`（未指定時 `~/.config/plime/<environment>/session.json`）へ保存します。POSIXではディレクトリ700、ファイル600です。暗号化保管やOS Keychainへの保存ではありません。Windowsでは保存先のユーザーACLに依存します。
+
+同時実行によるrefresh token再利用を防ぐため、認証情報の操作はファイルlockで直列化します。強制終了でlockが残った場合、他のplimeコマンドが動いていないことを確認して、エラーに表示された `session.lock` を削除してください。通信断でrefresh結果を受け取れなかった場合は、`logout --local` と再ログインで復旧します。
+
+ログアウトしてもブラウザのPLIMEセッションは維持されます。発行済みaccess tokenは期限まで有効になり得ます。`whoami`はJWTの有効性を確認するもので、サーバー上の失効を毎回照会するものではありません。
+
+利用開始にはIDPのmigration・公式CLIのprovisionと、accountsのログイン・同意画面のデプロイが必要です。`--dev`ではIDP localhost:8787、accounts localhost:3003を起動し、開発DBでもprovisionしてください。
+
+AIコマンドとAI API側のOAuth検証・利用認可・課金は未実装です。ログイン成功だけではAI APIの利用開始を意味しません。
+
+検証: package rootで `vp test run` と `vp lint`。実Better AuthとのOAuth統合テストはmonorepo内のIDPテストfixtureを使います。

package/bin/plime.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { run, errorMessage } from '../src/cli.js'
+
+const controller = new AbortController()
+const abort = () => controller.abort()
+process.once('SIGINT', abort)
+process.once('SIGTERM', abort)
+try {
+  await run(process.argv.slice(2), { signal: controller.signal })
+} catch (err) {
+  process.stderr.write(`plime: ${errorMessage(err)}\n`)
+  process.exitCode = controller.signal.aborted ? 130 : 1
+} finally {
+  process.removeListener('SIGINT', abort)
+  process.removeListener('SIGTERM', abort)
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@plime-inc/cli",
+  "version": "0.1.0",
+  "description": "PLIME command-line client",
+  "author": "@plime-kitajima",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "bin": {
+    "plime": "bin/plime.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {
+    "oauth4webapi": "^3.8.8"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,60 @@
+import { parseArgs } from 'node:util'
+import { getConfig } from './config.js'
+import { createStore, getStoreDirectory } from './store.js'
+import { createCommands } from './commands.js'
+
+const help = `Usage: plime <command> [options]
+
+Commands:
+  login                Sign in using your browser
+  logout               Revoke the CLI login and remove local tokens
+  whoami               Show the authenticated user ID
+
+Options:
+  --dev                Use local IDP with separate login storage
+  --json               Print machine-readable results
+  --no-browser         Print the login URL without opening a browser
+  --local              Logout locally without server revocation
+  --help, -h           Show help
+  --version, -v        Show version
+`
+
+export const run = async (args, { stdout = process.stdout, stderr = process.stderr, signal, env = process.env } = {}) => {
+  const { values, positionals } = parseArgs({
+    args, allowPositionals: true, strict: true,
+    options: {
+      dev: { type: 'boolean' }, json: { type: 'boolean' },
+      'no-browser': { type: 'boolean' }, local: { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+    },
+  })
+  if (values.version) {
+    const { default: manifest } = await import('../package.json', { with: { type: 'json' } })
+    stdout.write(`${manifest.version}\n`)
+    return
+  }
+  if (values.help || !positionals.length) { stdout.write(help); return }
+  const [ command ] = positionals
+  if (positionals.length !== 1 || ![ 'login', 'logout', 'whoami' ].includes(command)) throw new Error('Unknown command. Run plime --help.')
+  if (values['no-browser'] && command !== 'login') throw new Error('--no-browser is only available for login.')
+  if (values.local && command !== 'logout') throw new Error('--local is only available for logout.')
+  const config = getConfig(values.dev)
+  const store = createStore(getStoreDirectory(config.environment, env))
+  const commands = createCommands({ config, store, signal, report: message => stderr.write(`${message}\n`) })
+  const result = await commands[command]({ noBrowser: values['no-browser'], local: values.local })
+  if (values.json) { stdout.write(`${JSON.stringify(result)}\n`); return }
+  if (command === 'logout') {
+    stdout.write(values.local ? 'Local login removed. Server tokens were not revoked.\n' : 'Logged out.\n')
+  } else {
+    stdout.write(`${command === 'login' ? 'Logged in as' : 'User'}: ${result.userId}\nEnvironment: ${config.environment}\n`)
+  }
+}
+
+// OAuthの例外cause/bodyにはtokenが含まれ得るため、SDKの例外オブジェクトをログに出さない。
+export const errorMessage = (error) => {
+  if (error.error === 'access_denied') return 'Login was denied.'
+  if (error.error) return 'OAuth request failed. Check the IDP configuration and try logging in again.'
+  if ([ 'AbortError', 'TimeoutError' ].includes(error.name)) return 'Request cancelled or timed out.'
+  if (error.code?.startsWith('OAUTH_')) return 'OAuth response validation failed. Please try logging in again.'
+  return error.message || 'Command failed.'
+}

package/src/commands.js

@@ -0,0 +1,60 @@
+import { createOAuth, createLoginProof } from './oauth.js'
+import { createLoopback, openBrowser } from './loopback.js'
+
+export const createCommands = ({ config, store, signal, report, oauthFactory = createOAuth, browser = openBrowser }) => {
+  const login = ({ noBrowser = false } = {}) => store.withLock(async () => {
+    if (await store.read()) throw new Error('Already logged in. Run plime logout before switching accounts.')
+    const oauth = await oauthFactory(config, { signal })
+    const { state, verifier } = createLoginProof()
+    const loopback = await createLoopback({ path: config.callbackPath, state, signal })
+    try {
+      const url = await oauth.authorize(loopback.redirectUri, state, verifier)
+      report(`Open this URL to sign in:\n${url}`)
+      if (!noBrowser) {
+        // ブラウザ起動コマンドの終了待ちでcallback受信を止めない。
+        void browser(url).then(opened => { if (!opened) report('Open the URL above in your browser.') })
+      }
+      const callback = await loopback.callback
+      const session = await oauth.exchange(callback, loopback.redirectUri, state, verifier)
+      await store.write(session)
+      return oauth.identity(session.accessToken)
+    } finally {
+      await loopback.close()
+    }
+  }, signal)
+
+  const whoami = () => store.withLock(async () => {
+    let session = await store.read()
+    if (!session) throw new Error('Not logged in. Run plime login.')
+    if (session.issuer !== config.issuer || session.resource !== config.resource) throw new Error('Stored login does not match this environment.')
+    const oauth = await oauthFactory(config, { signal })
+    if (session.expiresAt <= Date.now() + 60_000) {
+      try {
+        session = await oauth.refresh(session.refreshToken)
+        await store.write(session)
+      } catch (err) {
+        if (err.error === 'invalid_grant') {
+          await store.remove()
+          throw new Error('Login expired or was revoked. Run plime login again.')
+        }
+        throw err
+      }
+    }
+    return oauth.identity(session.accessToken)
+  }, signal)
+
+  const logout = ({ local = false } = {}) => store.withLock(async () => {
+    if (!local) {
+      const session = await store.read()
+      if (session) {
+        if (session.issuer !== config.issuer || session.resource !== config.resource) throw new Error('Stored login does not match this environment.')
+        const oauth = await oauthFactory(config, { signal })
+        await oauth.revoke(session.refreshToken)
+      }
+    }
+    await store.remove()
+    return { loggedOut: true, localOnly: local }
+  }, signal)
+
+  return { login, whoami, logout }
+}

package/src/config.js

@@ -0,0 +1,10 @@
+// npm配布物はprivate workspace packageへ依存しない。IDPの登録値との一致は統合テストで確認する。
+export const getConfig = (development = false) => ({
+  environment: development ? 'development' : 'production',
+  issuer: development ? 'http://localhost:8787/api/auth' : 'https://idp.plime.com/api/auth',
+  resource: development ? 'http://localhost:8791' : 'https://ai.plime.com',
+  clientId: 'plime-cli',
+  scopes: [ 'ai:invoke', 'offline_access' ],
+  callbackPath: '/oauth/callback',
+  development,
+})

package/src/loopback.js

@@ -0,0 +1,63 @@
+import { createServer } from 'node:http'
+import { spawn } from 'node:child_process'
+
+// 認可コードだけをloopbackで受け取る。tokenはブラウザに返さない。
+export const createLoopback = async ({ path, state, signal, timeoutMs = 300_000 }) => {
+  let resolveCallback
+  let rejectCallback
+  const callback = new Promise((resolve, reject) => {
+    resolveCallback = resolve
+    rejectCallback = reject
+  })
+  // ブラウザ起動前に中断しても未処理rejectionにしない。
+  callback.catch(() => {})
+  const server = createServer((request, response) => {
+    response.setHeader('cache-control', 'no-store')
+    response.setHeader('referrer-policy', 'no-referrer')
+    response.setHeader('content-type', 'text/plain; charset=utf-8')
+    const url = new URL(request.url, redirectUri)
+    const expected = new URL(redirectUri)
+    if (request.headers.host !== expected.host || url.origin !== expected.origin || request.method !== 'GET' || url.pathname !== path) {
+      response.writeHead(404).end('Not found')
+      return
+    }
+    if (url.searchParams.getAll('state').length !== 1 || url.searchParams.get('state') !== state) {
+      response.writeHead(400).end('Invalid login state. Return to your terminal and try again.')
+      return
+    }
+    response.end('PLIME authorization received. Return to your terminal to check the login result.')
+    resolveCallback(url)
+  })
+  await new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', resolve)
+  })
+  const redirectUri = `http://127.0.0.1:${server.address().port}${path}`
+  const abort = () => rejectCallback(new Error('Login cancelled.'))
+  const timer = setTimeout(() => rejectCallback(new Error('Login timed out. Run plime login again.')), timeoutMs)
+  signal?.addEventListener('abort', abort, { once: true })
+  if (signal?.aborted) abort()
+  const close = async () => {
+    clearTimeout(timer)
+    signal?.removeEventListener('abort', abort)
+    await new Promise(resolve => {
+      server.close(resolve)
+      server.closeAllConnections()
+    })
+  }
+  return { redirectUri, callback, close }
+}
+
+// OS既定ブラウザをshellを介さず起動する。失敗時は表示済みURLを手動で開ける。
+export const openBrowser = (url) => new Promise((resolve) => {
+  const commands = {
+    darwin: [ 'open', [ url ] ],
+    linux: [ 'xdg-open', [ url ] ],
+    win32: [ 'rundll32.exe', [ 'url.dll,FileProtocolHandler', url ] ],
+  }
+  const command = commands[process.platform]
+  if (!command) return resolve(false)
+  const child = spawn(command[0], command[1], { stdio: 'ignore', shell: false })
+  child.once('error', () => resolve(false))
+  child.once('spawn', () => { child.unref(); resolve(true) })
+})

package/src/oauth.js

@@ -0,0 +1,89 @@
+import * as oauth from 'oauth4webapi'
+
+export const createOAuth = async (config, { signal, fetch: fetcher = globalThis.fetch } = {}) => {
+  const issuer = new URL(config.issuer)
+  const options = () => ({
+    signal: signal ? AbortSignal.any([ signal, AbortSignal.timeout(30_000) ]) : AbortSignal.timeout(30_000),
+    [oauth.allowInsecureRequests]: config.development,
+    [oauth.customFetch]: fetcher,
+  })
+  // discoveryで得たURLにも送信先制限を適用し、tokenを別originへ送信しない。
+  const discovery = await oauth.discoveryRequest(issuer, { ...options(), algorithm: 'oauth2' })
+  const server = await oauth.processDiscoveryResponse(issuer, discovery)
+  for (const key of [ 'authorization_endpoint', 'token_endpoint', 'revocation_endpoint', 'jwks_uri' ]) {
+    const endpoint = new URL(server[key])
+    if (endpoint.origin !== issuer.origin || endpoint.username || endpoint.password || endpoint.hash) {
+      throw new Error('IDP returned an unexpected OAuth endpoint.')
+    }
+  }
+  if (!server.code_challenge_methods_supported?.includes('S256')) throw new Error('IDP does not support S256 PKCE.')
+  const client = { client_id: config.clientId }
+  const authentication = oauth.None()
+
+  const authorize = async (redirectUri, state, verifier) => {
+    const url = new URL(server.authorization_endpoint)
+    url.search = new URLSearchParams({
+      client_id: config.clientId,
+      redirect_uri: redirectUri,
+      response_type: 'code',
+      scope: config.scopes.join(' '),
+      resource: config.resource,
+      state,
+      code_challenge: await oauth.calculatePKCECodeChallenge(verifier),
+      code_challenge_method: 'S256',
+    }).toString()
+    return url.href
+  }
+
+  const identity = async (accessToken) => {
+    // requestはローカル検証用。AI APIへのリクエストは送らない。
+    const request = new Request(config.resource, { headers: { authorization: `Bearer ${accessToken}` } })
+    const claims = await oauth.validateJwtAccessToken(server, request, config.resource, options())
+    const scopes = typeof claims.scope === 'string' ? claims.scope.split(' ') : []
+    if (claims.client_id !== config.clientId || !config.scopes.every(scope => scopes.includes(scope))) {
+      throw new Error('IDP returned a token for an unexpected client or scope.')
+    }
+    return { userId: claims.sub, issuer: claims.iss, resource: config.resource, scopes, expiresAt: claims.exp * 1000 }
+  }
+
+  const session = async (tokens) => {
+    if (!tokens.refresh_token || !Number.isFinite(tokens.expires_in) || tokens.expires_in <= 0 || tokens.token_type !== 'bearer') {
+      throw new Error('IDP did not return the required login tokens.')
+    }
+    const user = await identity(tokens.access_token)
+    return {
+      version: 1,
+      issuer: config.issuer,
+      resource: config.resource,
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      expiresAt: Math.min(user.expiresAt, Date.now() + tokens.expires_in * 1000),
+    }
+  }
+
+  const exchange = async (callback, redirectUri, state, verifier) => {
+    const parameters = oauth.validateAuthResponse(server, client, callback, state)
+    const response = await oauth.authorizationCodeGrantRequest(server, client, authentication, parameters, redirectUri, verifier, {
+      ...options(), additionalParameters: { resource: config.resource },
+    })
+    return session(await oauth.processAuthorizationCodeResponse(server, client, response))
+  }
+
+  const refresh = async (refreshToken) => {
+    const response = await oauth.refreshTokenGrantRequest(server, client, authentication, refreshToken, {
+      ...options(), additionalParameters: { resource: config.resource },
+    })
+    return session(await oauth.processRefreshTokenResponse(server, client, response))
+  }
+
+  const revoke = async (refreshToken) => {
+    const response = await oauth.revocationRequest(server, client, authentication, refreshToken, {
+      ...options(), additionalParameters: { token_type_hint: 'refresh_token' },
+    })
+    await oauth.processRevocationResponse(response)
+  }
+
+  return { authorize, exchange, refresh, revoke, identity }
+}
+
+export const createLoginProof = () => ({ state: oauth.generateRandomState(), verifier: oauth.generateRandomCodeVerifier() })

package/src/store.js

@@ -0,0 +1,87 @@
+import { constants } from 'node:fs'
+import { chmod, lstat, mkdir, open, readFile, rename, unlink } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { setTimeout as delay } from 'node:timers/promises'
+
+export const getStoreDirectory = (environment, env = process.env) => {
+  const base = env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  if (!isAbsolute(base)) throw new Error('XDG_CONFIG_HOME must be an absolute path.')
+  return join(base, 'plime', environment)
+}
+
+export const createStore = (directory) => {
+  const path = join(directory, 'session.json')
+  const lockPath = join(directory, 'session.lock')
+
+  // 所有者だけが参照できるディレクトリに認証情報を書き込む。
+  const prepare = async () => {
+    await mkdir(directory, { recursive: true, mode: 0o700 })
+    const info = await lstat(directory)
+    if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('Invalid PLIME config directory.')
+    await chmod(directory, 0o700)
+  }
+
+  const read = async () => {
+    try {
+      const info = await lstat(path)
+      if (!info.isFile() || info.isSymbolicLink()) throw new Error('Invalid PLIME session file.')
+      if (process.platform !== 'win32' && (info.mode & 0o077)) throw new Error('PLIME session file must have permission 600.')
+      const data = JSON.parse(await readFile(path, 'utf8'))
+      if (data.version !== 1 || typeof data.accessToken !== 'string' || !data.accessToken
+        || typeof data.refreshToken !== 'string' || !data.refreshToken
+        || !Number.isFinite(data.expiresAt) || typeof data.issuer !== 'string' || typeof data.resource !== 'string') {
+        throw new Error('Invalid PLIME session file. Run plime logout --local, then plime login.')
+      }
+      return data
+    } catch (err) {
+      if (err.code === 'ENOENT') return null
+      if (err instanceof SyntaxError) throw new Error('Invalid PLIME session file. Run plime logout --local, then plime login.')
+      throw err
+    }
+  }
+
+  // 一時ファイルを同じディレクトリで置換し、途中まで書いたtokenを残さない。
+  const write = async (data) => {
+    const temporary = join(directory, `session-${randomUUID()}.tmp`)
+    const file = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600)
+    try {
+      await file.writeFile(JSON.stringify(data), 'utf8')
+      await file.sync()
+      await file.close()
+      await rename(temporary, path)
+    } finally {
+      await file.close()
+      await unlink(temporary).catch(err => { if (err.code !== 'ENOENT') throw err })
+    }
+  }
+
+  const remove = () => unlink(path).catch(err => { if (err.code !== 'ENOENT') throw err })
+
+  // refresh tokenのローテーションを別プロセスとも直列化する。異常終了のlockは勝手に奪わない。
+  const withLock = async (operation, signal) => {
+    await prepare()
+    const deadline = Date.now() + 10_000
+    let lock
+    while (!lock) {
+      signal?.throwIfAborted()
+      try {
+        lock = await open(lockPath, 'wx', 0o600)
+      } catch (err) {
+        if (err.code !== 'EEXIST') throw err
+        if (Date.now() >= deadline) throw new Error(`Another plime command holds the session lock. If it crashed, remove ${lockPath} after confirming no plime command is running.`)
+        await delay(100, undefined, { signal })
+      }
+    }
+    try {
+      await lock.writeFile(String(process.pid))
+      return await operation()
+    } finally {
+      await lock.close()
+      await unlink(lockPath)
+    }
+  }
+
+  return { read, write, remove, withLock }
+}