feat(oauth): restack OAuth backbone

Restack the OAuth backend from PR #5584 onto current master for PAP-9233, preserving the provider registry, OAuth routes, refresh worker, resolver integration, tests, and docs.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

packages/plugins/sdk/src/__tests__/define-oauth-provider.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { defineOAuthProvider } from "../define-oauth-provider.js";
+
+describe("defineOAuthProvider", () => {
+  it("returns its input unchanged (identity helper)", () => {
+    const contribution = {
+      config: {
+        id: "x",
+        displayName: "X",
+        clientCredentials: { clientIdEnv: "X_ID", clientSecretEnv: "X_SECRET" },
+        endpoints: {
+          authorize: "https://x.example/a",
+          token: "https://x.example/t",
+          accountInfo: "https://x.example/me",
+        },
+        scopes: { default: [], offered: [] },
+        pkce: "required" as const,
+        authMethod: "post" as const,
+        responseFormat: "json" as const,
+        accountIdField: "id",
+        accountLabelField: "name",
+        refresh: { supported: false as const },
+      },
+    };
+    expect(defineOAuthProvider(contribution)).toBe(contribution);
+  });
+});

packages/plugins/sdk/src/define-oauth-provider.ts

@@ -0,0 +1,16 @@
+import type { OAuthProviderContribution } from "@paperclipai/shared";
+
+/**
+ * Identity helper for plugin authors contributing OAuth providers.
+ *
+ * Returns the contribution unchanged. The function exists purely for type
+ * inference and editor autocomplete: declaring a contribution via
+ * `defineOAuthProvider({...})` constrains the literal to
+ * {@link OAuthProviderContribution} so authors get errors before the host
+ * runs Zod validation at registration time.
+ */
+export function defineOAuthProvider<T extends OAuthProviderContribution>(
+  contribution: T,
+): T {
+  return contribution;
+}

packages/plugins/sdk/src/index.ts

@@ -50,6 +50,7 @@
 // ---------------------------------------------------------------------------
 
 export { definePlugin } from "./define-plugin.js";
+export { defineOAuthProvider } from "./define-oauth-provider.js";
 export { createTestHarness, createEnvironmentTestHarness, createFakeEnvironmentDriver, filterEnvironmentEvents, assertEnvironmentEventOrder, assertLeaseLifecycle, assertWorkspaceRealizationLifecycle, assertExecutionLifecycle, assertEnvironmentError } from "./testing.js";
 export { createPluginBundlerPresets } from "./bundlers.js";
 export { startPluginDevServer, getUiBuildSnapshot } from "./dev-server.js";

packages/plugins/sdk/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+  },
+});