認証

認証プロバイダーは、どのトークンを送るかを Nodaro SDK に伝えます。クライアントはリクエストのたびに、プロバイダーの getToken() を呼び出し、その結果を Authorization: Bearer <token> として送信します。プロバイダーが null を返した場合、リクエストは、匿名のリクエストとしてヘッダーなしで送られます。

プロバイダーを選ぶ

使えるトークン

• API トークンは、利用額の上限がない永続的な認証情報です。無効にするか削除するまで使えるので、サーバーに保管してください。上限とレート設定については、API 認証を参照してください。
• OAuth アクセストークンは、ユーザーが承認したスコープだけを持ちます。あなたのアプリがほかの人の代わりに動作する場合に使います。OAuth を参照してください。
• セルフホスティングの Community エディションのインストール環境では、アプリは API トークンを提供しません。代わりにログインし、supabaseAuth または CallbackAuth でセッショントークンを使ってください。

Auth インターフェース

interface Auth {
  getToken(): Promise<string | null>
}

この形を持つオブジェクトなら何でも、createClient の auth オプションにできます。以下の 3 つのプロバイダーは、これを実装しています。

StaticTokenAuth

new StaticTokenAuth(token: string)

1 つの固定トークンをラップします。プロセスの実行中にトークンが変わらない場合に使います。API トークンや、あなたのサーバーが認可コードフローで取得した OAuth アクセストークンなどです。

import { createClient, StaticTokenAuth } from "@nodaro/sdk"

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
})

CallbackAuth

new CallbackAuth(fn: () => string | null | Promise<string | null>)

リクエストのたびにあなたの関数を呼び出し、その関数が返すトークンを送信します。関数は同期でも非同期でもかまいません。トークンなしでリクエストを送るには、null を返します。

トークンの更新、独自のセッションストアの読み取り、認証情報のローテーションに使います。

import { createClient, CallbackAuth } from "@nodaro/sdk"

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new CallbackAuth(async () => {
    const session = await sessionStore.read()
    if (!session) return null
    if (Date.now() > session.expiresAt - 60_000) {
      await refresh(session)
    }
    return session.accessToken
  }),
})

supabaseAuth(supabase)

supabaseAuth(supabase: SupabaseLikeClient): Auth

リクエストのたびに、Supabase v2 クライアントからログイン中のユーザーのトークンを読み取ります。ユーザーが同じ Nodaro インスタンスにログインするブラウザーアプリ、たとえばセルフホスティング環境向けの自作フロントエンドで使います。Nodaro のエディター自体も、同じプロバイダーを使っています。トークンはそのつど読み取られるため、更新されたセッションも自動的に反映されます。

import { createClient, supabaseAuth } from "@nodaro/sdk"
import { createClient as createSupabase } from "@supabase/supabase-js"

const supabase = createSupabase(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_ANON_KEY,
)

const client = createClient({
  baseUrl: import.meta.env.VITE_API_URL ?? "",
  auth: supabaseAuth(supabase),
})

誰もログインしていない場合、リクエストはトークンなしで送られます。

createSharedSupabaseClient(options)

import { createSharedSupabaseClient } from "@nodaro/sdk/supabase"

createSharedSupabaseClient<Db = any>(options: {
  url: string
  anonKey: string
  cookieDomain?: string
}): SupabaseClient<Db>

セッションをローカルストレージではなくクッキーに保存する、ブラウザー用の Supabase クライアントを作成します。cookieDomain を指定すると、同じ親ドメインの下にある複数のサブドメインのアプリが、1 つのログインを共有します。いずれか 1 つでログインすると、すべてでログイン状態になり、いずれか 1 つでログアウトすると、すべてでログアウトします。

import { createClient, supabaseAuth } from "@nodaro/sdk"
import { createSharedSupabaseClient } from "@nodaro/sdk/supabase"

const supabase = createSharedSupabaseClient({
  url: SUPABASE_URL,
  anonKey: SUPABASE_ANON_KEY,
  cookieDomain: ".example.com",
})

const client = createClient({ baseUrl: "", auth: supabaseAuth(supabase) })

• cookieDomain が適用されるのは、ページのホストがそのドメインか、そのサブドメインのいずれかである場合だけです。localhost やプレビュー URL など、それ以外のホストでは、クッキーは現在のホストにとどまるため、ローカル開発ではオリジンごとに別々のセッションになります。
• 最初の読み込み時に、ローカルストレージにある既存のセッションがクッキーに移され、古いエントリーは削除されます。すでにログインしていたユーザーは、ログイン状態のままになります。期限切れのセッションは破棄されます。
• このエクスポートは、独立したパス @nodaro/sdk/supabase にあります。そのため、メインパッケージは Supabase に依存しません。使うには @supabase/supabase-js と @supabase/ssr をインストールしてください。

スコープと不足している権限

OAuth アクセストークンは、ユーザーが承認したスコープ（workflows:read や workflows:execute など）を持ちます。各リソースのリファレンスページには、そのメソッドが必要とするスコープが明記されています。トークンにスコープが不足している場合、メソッドは ForbiddenError をスローし、その missingScope に不足しているスコープが示されます。

import { ForbiddenError } from "@nodaro/sdk"

try {
  await client.workflows.run(workflowId)
} catch (err) {
  if (err instanceof ForbiddenError && err.missingScope) {
    requestConsentFor([err.missingScope]) // send the user through OAuth again
  } else {
    throw err
  }
}

API トークンとセッショントークンは、スコープによる制限を受けません。エラークラスの一覧については、エラーを参照してください。

ブラウザーのルール

• API トークンを決してブラウザーに渡さないでください。ページから誰でも読み取れてしまい、あなたとして動作してしまいます。
• ブラウザーでの OAuth トークンは、あなたの開発者アプリの allowedOrigins に登録されたオリジンからしか動作しません。OAuth と開発者アプリを参照してください。
• supabaseAuth によるセッショントークンは、そのリストと照合されません。
• シークレットはサーバーに置いてください。OAuth のコード交換にはクライアントシークレットが必要なので、client.oauth.exchangeCode() はサーバーのコードでだけ実行してください。