@airdraft/cloud-auth 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+All notable changes to `@airdraft/cloud-auth` will be documented here.
+
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.

package/dist/BetterAuthAdapter.d.ts

@@ -0,0 +1,74 @@
+import type { CloudAuthAdapter } from './types.js';
+interface BetterAuthSession {
+    user: {
+        id: string;
+        email: string;
+        name?: string | null;
+        image?: string | null;
+    };
+    session: unknown;
+}
+/**
+ * Minimal structural interface for a `betterAuth(...)` instance.
+ * Accepts the real Better Auth instance without requiring an exact type import.
+ */
+export interface BetterAuthLike {
+    /** Fetch-compatible catch-all route handler. */
+    handler: (req: Request) => Promise<Response>;
+    api: {
+        /** Resolves the session from request headers. Returns null if unauthenticated. */
+        getSession(opts: {
+            headers: Headers;
+        }): Promise<BetterAuthSession | null>;
+        /**
+         * Create a user account. Requires the Better Auth `admin` plugin.
+         * @see https://better-auth.com/docs/plugins/admin
+         */
+        adminCreateUser?(opts: {
+            body: {
+                email: string;
+                name?: string;
+                password?: string;
+                role?: string;
+                data?: Record<string, unknown>;
+            };
+        }): Promise<{
+            user: {
+                id: string;
+            };
+        }>;
+        /**
+         * Delete a user account and all associated sessions.
+         * Requires the Better Auth `admin` plugin.
+         */
+        adminRemoveUser?(opts: {
+            body: {
+                userId: string;
+            };
+        }): Promise<void>;
+    };
+}
+/**
+ * Wraps a `betterAuth(...)` instance to satisfy the `CloudAuthAdapter` interface.
+ *
+ * The `admin` plugin must be enabled on the Better Auth instance for
+ * `createUser` and `deleteUser` to work.
+ *
+ * ```ts
+ * import { betterAuth } from 'better-auth'
+ * import { admin } from 'better-auth/plugins'
+ * import { mongodbAdapter } from 'better-auth/adapters/mongodb'
+ * import { createBetterAuthAdapter } from '@airdraft/cloud-auth/better-auth'
+ *
+ * export const auth = betterAuth({
+ *   database: mongodbAdapter(db),
+ *   emailAndPassword: { enabled: true },
+ *   plugins: [admin()],
+ * })
+ *
+ * export const authAdapter = createBetterAuthAdapter(auth)
+ * ```
+ */
+export declare function createBetterAuthAdapter(auth: BetterAuthLike): CloudAuthAdapter;
+export {};
+//# sourceMappingURL=BetterAuthAdapter.d.ts.map

package/dist/BetterAuthAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BetterAuthAdapter.d.ts","sourceRoot":"","sources":["../src/BetterAuthAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAkC,MAAM,YAAY,CAAA;AAUlF,UAAU,iBAAiB;IACzB,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAA;QACV,KAAK,EAAE,MAAM,CAAA;QACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QACpB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KACtB,CAAA;IACD,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC5C,GAAG,EAAE;QACH,kFAAkF;QAClF,UAAU,CAAC,IAAI,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;QACzE;;;WAGG;QACH,eAAe,CAAC,CAAC,IAAI,EAAE;YACrB,IAAI,EAAE;gBACJ,KAAK,EAAE,MAAM,CAAA;gBACb,IAAI,CAAC,EAAE,MAAM,CAAA;gBACb,QAAQ,CAAC,EAAE,MAAM,CAAA;gBACjB,IAAI,CAAC,EAAE,MAAM,CAAA;gBACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;aAC/B,CAAA;SACF,GAAG,OAAO,CAAC;YAAE,IAAI,EAAE;gBAAE,EAAE,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,CAAC,CAAA;QACrC;;;WAGG;QACH,eAAe,CAAC,CAAC,IAAI,EAAE;YAAE,IAAI,EAAE;gBAAE,MAAM,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KACpE,CAAA;CACF;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CA6C9E"}

package/dist/BetterAuthAdapter.js

@@ -0,0 +1,65 @@
+// ---------------------------------------------------------------------------
+// BetterAuthAdapter factory
+// ---------------------------------------------------------------------------
+/**
+ * Wraps a `betterAuth(...)` instance to satisfy the `CloudAuthAdapter` interface.
+ *
+ * The `admin` plugin must be enabled on the Better Auth instance for
+ * `createUser` and `deleteUser` to work.
+ *
+ * ```ts
+ * import { betterAuth } from 'better-auth'
+ * import { admin } from 'better-auth/plugins'
+ * import { mongodbAdapter } from 'better-auth/adapters/mongodb'
+ * import { createBetterAuthAdapter } from '@airdraft/cloud-auth/better-auth'
+ *
+ * export const auth = betterAuth({
+ *   database: mongodbAdapter(db),
+ *   emailAndPassword: { enabled: true },
+ *   plugins: [admin()],
+ * })
+ *
+ * export const authAdapter = createBetterAuthAdapter(auth)
+ * ```
+ */
+export function createBetterAuthAdapter(auth) {
+    return {
+        async verifySession(req) {
+            const session = await auth.api.getSession({ headers: req.headers });
+            if (!session)
+                return null;
+            return {
+                userId: session.user.id,
+                email: session.user.email,
+                name: session.user.name ?? undefined,
+                avatarUrl: session.user.image ?? undefined,
+            };
+        },
+        handler(req) {
+            return auth.handler(req);
+        },
+        async createUser(input) {
+            if (!auth.api.adminCreateUser) {
+                throw new Error('@airdraft/cloud-auth: createUser requires the Better Auth `admin` plugin. ' +
+                    'Add `admin()` to your betterAuth plugins array.');
+            }
+            const result = await auth.api.adminCreateUser({
+                body: {
+                    email: input.email,
+                    name: input.name,
+                    password: input.password,
+                    data: input.emailVerified ? { emailVerified: true } : undefined,
+                },
+            });
+            return result.user.id;
+        },
+        async deleteUser(userId) {
+            if (!auth.api.adminRemoveUser) {
+                throw new Error('@airdraft/cloud-auth: deleteUser requires the Better Auth `admin` plugin. ' +
+                    'Add `admin()` to your betterAuth plugins array.');
+            }
+            await auth.api.adminRemoveUser({ body: { userId } });
+        },
+    };
+}
+//# sourceMappingURL=BetterAuthAdapter.js.map

package/dist/BetterAuthAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BetterAuthAdapter.js","sourceRoot":"","sources":["../src/BetterAuthAdapter.ts"],"names":[],"mappings":"AAmDA,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAoB;IAC1D,OAAO;QACL,KAAK,CAAC,aAAa,CAAC,GAAY;YAC9B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAA;YACnE,IAAI,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAA;YACzB,OAAO;gBACL,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE;gBACvB,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK;gBACzB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,SAAS;gBACpC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,SAAS;aAC3C,CAAA;QACH,CAAC;QAED,OAAO,CAAC,GAAY;YAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC1B,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,KAAsB;YACrC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CACb,4EAA4E;oBAC1E,iDAAiD,CACpD,CAAA;YACH,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC;gBAC5C,IAAI,EAAE;oBACJ,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS;iBAChE;aACF,CAAC,CAAA;YACF,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAA;QACvB,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,MAAc;YAC7B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CACb,4EAA4E;oBAC1E,iDAAiD,CACpD,CAAA;YACH,CAAC;YACD,MAAM,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAA;QACtD,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { CloudAuthAdapter, CloudIdentity, CreateUserInput } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Minimal identity returned for every verified session.
+ * Downstream code looks up team membership separately.
+ */
+export interface CloudIdentity {
+    userId: string;
+    email: string;
+    name?: string;
+    avatarUrl?: string;
+}
+/**
+ * Input for programmatic user creation (e.g. during invite acceptance).
+ */
+export interface CreateUserInput {
+    email: string;
+    name?: string;
+    /** Only required for email/password auth. Adapters that don't use passwords may ignore it. */
+    password?: string;
+    /** Whether the email is pre-verified (e.g. for invited users). Default: false. */
+    emailVerified?: boolean;
+}
+/**
+ * Pluggable authentication adapter for the Airdraft Cloud dashboard.
+ *
+ * The default implementation wraps Better Auth (`createBetterAuthAdapter`),
+ * but any object implementing this interface can be used.
+ *
+ * ```ts
+ * // Default (Better Auth):
+ * import { createBetterAuthAdapter } from '@airdraft/cloud-auth/better-auth'
+ * const authAdapter = createBetterAuthAdapter(betterAuthInstance)
+ *
+ * // Custom:
+ * const authAdapter: CloudAuthAdapter = {
+ *   async verifySession(req) { ... },
+ *   async handler(req)       { ... },
+ *   async createUser(input)  { ... },
+ *   async deleteUser(userId) { ... },
+ * }
+ * ```
+ */
+export interface CloudAuthAdapter {
+    /**
+     * Verify an inbound request and return the caller's identity.
+     * Returns `null` for unauthenticated requests — callers should return 401.
+     */
+    verifySession(req: Request): Promise<CloudIdentity | null>;
+    /**
+     * Catch-all HTTP handler for auth endpoints (login, logout, OAuth callback,
+     * magic link, OTP, etc.). Mount at `/api/auth/[...all]` in the cloud app.
+     */
+    handler(req: Request): Promise<Response>;
+    /**
+     * Create a new user account. Returns the new user's ID.
+     * Called during invite acceptance to provision the account.
+     */
+    createUser(input: CreateUserInput): Promise<string>;
+    /**
+     * Delete a user account and invalidate all their sessions.
+     * Called when a user closes their account.
+     */
+    deleteUser(userId: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAE1D;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAExC;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEnD;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C"}

package/dist/types.js

@@ -0,0 +1,18 @@
+// ---------------------------------------------------------------------------
+// CloudAuthAdapter — pluggable session layer for the Airdraft Cloud dashboard
+//
+// Implement this interface to swap the auth backend (Better Auth, Clerk,
+// custom JWT, etc.) without touching any other part of the cloud app.
+//
+// The adapter is responsible for:
+//   - Verifying inbound requests and returning the caller's identity
+//   - Owning the auth HTTP handler (/api/auth/[...all])
+//   - Creating and deleting user accounts
+//
+// The adapter is NOT responsible for:
+//   - Team / org membership (Airdraft-owned MongoDB collections)
+//   - Project access control (Airdraft service layer)
+//   - `ntk_` API key verification (@airdraft/auth, unchanged)
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8EAA8E;AAC9E,EAAE;AACF,yEAAyE;AACzE,sEAAsE;AACtE,EAAE;AACF,kCAAkC;AAClC,qEAAqE;AACrE,wDAAwD;AACxD,0CAA0C;AAC1C,EAAE;AACF,sCAAsC;AACtC,iEAAiE;AACjE,sDAAsD;AACtD,8DAA8D;AAC9D,8EAA8E"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@airdraft/cloud-auth",
+  "version": "0.1.0",
+  "description": "Airdraft Cloud auth adapter interface — pluggable session verification for the cloud dashboard",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./better-auth": {
+      "import": "./dist/BetterAuthAdapter.js",
+      "types": "./dist/BetterAuthAdapter.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "release": "standard-version",
+    "release:patch": "standard-version --release-as patch",
+    "release:minor": "standard-version --release-as minor",
+    "release:major": "standard-version --release-as major"
+  },
+  "publishConfig": { "access": "public" },
+  "license": "MIT",
+  "peerDependencies": {
+    "better-auth": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-auth": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "better-auth": "^1.0.0",
+    "standard-version": "^9.5.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.5.0"
+  },
+  "engines": { "node": ">=18.0.0" }
+}