@gasboost/auth-realtime-firebase 0.1.0

package/README.md

@@ -0,0 +1,196 @@
+# @gasboost/auth-realtime-firebase
+
+Firebase Authentication integration adapter for `@gasboost/auth`.
+
+`@gasboost/auth` の認証 lifecycle と、`@gasboost/realtime-firebase` の Firebase Custom Token generation を接続します。
+
+```text
+@gasboost/auth
+      ↓ afterSignIn
+@gasboost/auth-realtime-firebase
+      ↓
+@gasboost/realtime-firebase
+      ↓
+Firebase Custom Token
+```
+
+## Install
+
+```bash
+pnpm add \
+  @gasboost/auth \
+  @gasboost/auth-realtime-firebase \
+  @gasboost/realtime-firebase
+```
+
+## Usage
+
+```ts
+import { AppsScriptAuth, type EmailPasswordAuthOptions } from "@gasboost/auth";
+import {
+  FirebaseAuthHook,
+  type FirebaseAuthHookResult,
+} from "@gasboost/auth-realtime-firebase";
+
+const firebase = new FirebaseAuthHook({
+  serviceAccount: {
+    email: serviceAccountEmail,
+    privateKey,
+  },
+
+  utilities: Utilities,
+});
+
+const auth = new AppsScriptAuth<
+  EmailPasswordAuthOptions,
+  FirebaseAuthHookResult
+>({
+  repository,
+
+  runtime: {
+    utilities: Utilities,
+    session: Session,
+    cacheService: CacheService,
+    propertiesService: PropertiesService,
+  },
+
+  session: {
+    storageType: "cache",
+  },
+
+  emailPassword: {
+    enabled: true,
+    pepper,
+  },
+
+  hooks: {
+    afterSignIn: firebase.afterSignIn,
+  },
+});
+```
+
+Sign In result から Firebase Custom Token を取得できます。
+
+```ts
+const result = await auth.signIn.email({
+  email: "user@example.com",
+  password: "password",
+});
+
+result.user;
+result.session;
+result.hooks.customToken;
+```
+
+## UID
+
+Gasboost Auth の `User.id` を Firebase Authentication の `uid` として利用します。
+
+```text
+Auth User.id
+    ↓
+Firebase uid
+```
+
+adapter側で別のFirebase User IDを管理する必要はありません。
+
+## Custom Claims
+
+`claims` を指定すると Firebase Custom Token の custom claims を生成できます。
+
+```ts
+const firebase = new FirebaseAuthHook({
+  serviceAccount: {
+    email: serviceAccountEmail,
+    privateKey,
+  },
+
+  utilities: Utilities,
+
+  claims: ({ user, session }) => ({
+    storeId: "store-1",
+    authSessionId: session.id,
+  }),
+});
+```
+
+生成されたclaimsはFirebase Authentication後、
+
+```text
+auth.token.storeId
+```
+
+などとしてFirebase Security Rulesから参照できます。
+
+## Service Account
+
+Firebase Custom Token は Google Service Account によって署名する必要があります。
+
+このpackageでは `@gasboost/realtime-firebase` のローカル署名方式を利用するため、以下が必要です。
+
+```ts
+serviceAccount: {
+  email: serviceAccountEmail,
+  privateKey,
+}
+```
+
+private key はソースコードへ直接埋め込まず、安全なcredential storageから取得してください。
+
+Service Account credentialの保存やSecret Manager integrationは、このpackageの責務ではありません。
+
+## GAS Utilities
+
+署名処理にはGoogle Apps Script標準の `Utilities` を利用できます。
+
+```ts
+const firebase = new FirebaseAuthHook({
+  serviceAccount,
+  utilities: Utilities,
+});
+```
+
+公開APIはGAS固有型には依存していないため、実際の署名処理は `@gasboost/realtime-firebase` が要求する最小interfaceを通じて実行されます。
+
+## Client
+
+Sign Inで取得したCustom Tokenはfrontendへ返し、Firebase公式SDKへ渡します。
+
+```ts
+import { getAuth, signInWithCustomToken } from "firebase/auth";
+
+await signInWithCustomToken(getAuth(), result.hooks.customToken);
+```
+
+このpackageはFirebase Browser SDKをラップしません。
+
+## Package Boundary
+
+このpackageが担当するのは integration のみです。
+
+```text
+AfterSignInContext
+   ├─ User
+   └─ Session
+        ↓
+FirebaseAuthHook
+        ↓
+uid / claims
+        ↓
+FirebaseCustomToken.generate()
+```
+
+以下は担当しません。
+
+- Gasboost Auth の認証処理
+- Firebase Custom Token JWT生成ロジック
+- Firebase Admin SDK
+- Firebase Browser SDK
+- `signInWithCustomToken()` の実行
+- Firebase Auth session管理
+- Service Account credential storage
+- Secret Manager integration
+
+## License
+
+MIT

package/dist/FirebaseAuthHook.d.ts

@@ -0,0 +1,16 @@
+import type { AfterSignInContext, AfterSignInHook } from "@gasboost/auth";
+import { type FirebaseCustomClaims, type FirebaseCustomTokenUtilities, type FirebaseServiceAccount } from "@gasboost/realtime-firebase";
+export type FirebaseAuthHookResult = {
+    readonly customToken: string;
+};
+export declare class FirebaseAuthHook {
+    private readonly serviceAccount;
+    private readonly utilities;
+    private readonly claims;
+    constructor({ serviceAccount, utilities, claims, }: {
+        serviceAccount: FirebaseServiceAccount;
+        utilities: FirebaseCustomTokenUtilities;
+        claims?: (context: AfterSignInContext) => FirebaseCustomClaims;
+    });
+    readonly afterSignIn: AfterSignInHook<FirebaseAuthHookResult>;
+}

package/dist/FirebaseAuthHook.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirebaseAuthHook = void 0;
+const realtime_firebase_1 = require("@gasboost/realtime-firebase");
+class FirebaseAuthHook {
+    constructor({ serviceAccount, utilities, claims, }) {
+        this.afterSignIn = (context) => {
+            return {
+                customToken: realtime_firebase_1.FirebaseCustomToken.generate({
+                    uid: context.user.id,
+                    claims: this.claims?.(context),
+                    serviceAccount: this.serviceAccount,
+                    utilities: this.utilities,
+                }),
+            };
+        };
+        this.serviceAccount = serviceAccount;
+        this.utilities = utilities;
+        this.claims = claims;
+    }
+}
+exports.FirebaseAuthHook = FirebaseAuthHook;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./FirebaseAuthHook";

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./FirebaseAuthHook"), exports);

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@gasboost/auth-realtime-firebase",
+  "version": "0.1.0",
+  "description": "Firebase Authentication integration adapter for @gasboost/auth.",
+  "keywords": [
+    "google-apps-script",
+    "gas",
+    "authentication",
+    "auth",
+    "firebase",
+    "firebase-authentication",
+    "custom-token",
+    "typescript",
+    "gasboost"
+  ],
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gasboost/auth.git",
+    "directory": "packages/auth-realtime-firebase"
+  },
+  "bugs": {
+    "url": "https://github.com/gasboost/auth/issues"
+  },
+  "homepage": "https://github.com/gasboost/auth#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@gasboost/realtime-firebase": "^0.2.0",
+    "@gasboost/auth": "0.2.0"
+  },
+  "devDependencies": {
+    "@gasboost/fake-node": "^0.1.2",
+    "@types/node": "^26.4.1"
+  },
+  "scripts": {
+    "format": "prettier --check . --config ../../.prettierrc.json --ignore-path ../../.prettierignore",
+    "format:fix": "prettier --write . --config ../../.prettierrc.json --ignore-path ../../.prettierignore",
+    "lint": "eslint . --config ../../eslint.config.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  }
+}