1 files changed, 48 insertions, 0 deletions
diff --git a/packages/kernel/src/contracts/auth.ts b/packages/kernel/src/contracts/auth.ts
new file mode 100644
index 0000000..6058156
--- /dev/null
+++ b/packages/kernel/src/contracts/auth.ts
@@ -0,0 +1,48 @@
+/**
+ * Auth contract — how a provider obtains credentials.
+ *
+ * Kept minimal and general. The common case is API-key + base-URL; richer
+ * flows (OAuth, token refresh) are handled by specific auth extensions that
+ * still resolve to credentials the provider can consume.
+ */
+
+/**
+ * The simplest credential set: an API key and optional base URL.
+ * This is the common case for OpenAI-compatible and most provider extensions.
+ */
+export interface ApiKeyCredentials {
+	readonly type: "api-key";
+	readonly apiKey: string;
+	readonly baseURL?: string;
+}
+
+/**
+ * Bearer token credentials (e.g. OAuth access tokens).
+ * The auth extension is responsible for refresh logic; the provider
+ * receives a currently-valid token.
+ */
+export interface BearerTokenCredentials {
+	readonly type: "bearer-token";
+	readonly token: string;
+	readonly baseURL?: string;
+}
+
+/** Union of credential shapes the kernel recognizes. */
+export type Credentials = ApiKeyCredentials | BearerTokenCredentials;
+
+/**
+ * What an auth extension registers with the kernel. A provider resolves its
+ * credentials through this contract — the kernel never touches secrets
+ * directly (the concrete vault is a core extension).
+ */
+export interface AuthContract {
+	/** Unique identifier for this auth provider (e.g. "apikey", "claude-oauth"). */
+	readonly id: string;
+
+	/**
+	 * Resolve currently-valid credentials. May involve reading from the
+	 * secret vault (injected via Host API) or performing a token refresh.
+	 * Returns `null` if credentials are unavailable (e.g. not yet configured).
+	 */
+	readonly resolve: () => Promise<Credentials | null>;
+}