extension-openai

This extension is the mandatory recipe for any Caffeine build that calls OpenAI, covering ChatGPT, GPT models, general LLM use, chatbots, and embeddings. The only supported path is the openai-client mops package (curated Motoko bindings for the OpenAI REST API generated from OpenAPI spec 2.3.0, with a curated subset spanning Chat, Completions, Embeddings, Images, Audio, Moderations, Models, and Files) using a canister-side API-key bearer. Hand-rolling ic.http_request calls to api.openai.com/v1/... is a forbidden anti-pattern because it leaks the bearer across replicated outcalls (a security and roughly 13x billing impact), bypasses the typed request/response bindings, and forces hand-rolled JSON on a language with weak JSON support.

Unlike X, OpenAI uses a single static bearer per account, an sk-... key, with no OAuth, PKCE, callback URL, or refresh rotation. The skill defines three storage variants the spec picks from: per-user keys (the default) where each signed-in user pastes their own sk-... key and funds their own usage, gated on a non-anonymous caller; an admin key set once by an admin and used for every call, gated on the extension-authorization #admin role, for operator-funded SaaS or freemium tiers; and a fully anonymous variant with no auth gate where any visitor may set or replace the single key, used only when the spec is explicit that there is no login. extension-authorization is a prerequisite for the per-user and admin-key variants (it ships the Internet Identity login flow and backend caller/role infrastructure), while the fully anonymous variant does not require it.

All variants share strict security invariants. The Config value must pin is_replicated = ?false, the package must be at least openai-client 0.2.5 (added with mops add [email protected], which requires Mops at least 2.13 for atomic lockfile updates), and the key must never be returned by any query or shared function, never logged, never sent to the frontend, and never placed in a stable variable that a weaker-gated endpoint could read. The frontend only ever learns whether a key is configured, as a Bool, never the key value. The bearer is long-lived with no expiry, has full unscoped account access, and should be treated as a billing credential rather than a session token. Use this skill for any feature that summarizes, classifies, answers, builds a chatbot, or generates embeddings via OpenAI.