@gasboost/auth 0.1.0 → 0.2.0

package/README.md

@@ -247,6 +247,177 @@ User 検索
 Session 発行
 ```
 
+## Authentication Hooks
+
+`@gasboost/auth` は、認証成功後に外部処理を実行するための lifecycle hook を提供します。
+
+現在は `afterSignIn` を利用できます。
+
+```ts
+import { AppsScriptAuth, type EmailPasswordAuthOptions } from "@gasboost/auth";
+
+type HookResult = {
+  readonly customToken: string;
+};
+
+const auth = new AppsScriptAuth<EmailPasswordAuthOptions, HookResult>({
+  repository,
+  runtime,
+
+  session: {
+    storageType: "cache",
+  },
+
+  emailPassword: {
+    enabled: true,
+    pepper,
+  },
+
+  hooks: {
+    afterSignIn: ({ user, session }) => ({
+      customToken: `${user.id}:${session.id}`,
+    }),
+  },
+});
+```
+
+`afterSignIn` には、認証された `User` と発行済みの `Session` が渡されます。
+
+```ts
+hooks: {
+  afterSignIn: ({ user, session }) => {
+    user.id;
+    session.id;
+
+    return {
+      customToken: "...",
+    };
+  },
+},
+```
+
+hook の戻り値は Sign In result の `hooks` から取得できます。
+
+```ts
+const result = await auth.signIn.email({
+  email: "user@example.com",
+  password: "password",
+});
+
+result.user;
+result.session;
+result.hooks.customToken;
+```
+
+hook result の型は `AppsScriptAuth` の第2型引数として指定できます。
+
+```ts
+type HookResult = {
+  readonly customToken: string;
+};
+
+const auth = new AppsScriptAuth<EmailPasswordAuthOptions, HookResult>({
+  // ...
+});
+```
+
+hook を設定しない場合、従来どおり Sign In result は `user` と `session` のみを返します。
+
+```ts
+const auth = new AppsScriptAuth({
+  repository,
+  runtime,
+
+  session: {
+    storageType: "cache",
+  },
+});
+
+const result = await auth.signIn.appsScript({});
+
+result.user;
+result.session;
+```
+
+### Async Hook
+
+`afterSignIn` は async 処理にも対応しています。
+
+```ts
+hooks: {
+  afterSignIn: async ({ user, session }) => {
+    const value = await createExternalCredential({
+      user,
+      session,
+    });
+
+    return {
+      value,
+    };
+  },
+},
+```
+
+### Hook Failure
+
+`afterSignIn` は Sign In 処理の一部として扱われます。
+
+処理順序は以下です。
+
+```text
+authentication
+      ↓
+User
+      ↓
+Session 発行
+      ↓
+Session 保存
+      ↓
+afterSignIn
+      ↓
+Sign In result
+```
+
+`afterSignIn` で例外が発生した場合、Sign In 全体が失敗します。
+
+その際、すでに保存された Session は SessionStorage から削除されます。
+
+```text
+afterSignIn error
+      ↓
+Session 削除
+      ↓
+error を呼び出し元へ伝播
+```
+
+これにより、外部認証情報などの生成に失敗したにもかかわらず、Gasboost 側の Session だけが有効な状態になることを防ぎます。
+
+### Package Boundary
+
+hooks API 自体は Firebase やその他の外部サービスを認識しません。
+
+```text
+@gasboost/auth
+  ↓
+afterSignIn
+  ↓
+external integration
+```
+
+例えば Firebase Custom Token を発行する場合でも、Firebase 固有の token generation は `@gasboost/auth` の責務には含めません。
+
+```text
+@gasboost/auth
+      ↓
+afterSignIn
+      ↓
+Firebase integration package
+      ↓
+Firebase Custom Token
+```
+
+`@gasboost/auth` は認証 lifecycle と拡張ポイントのみを提供し、外部サービス固有の処理は別 package から hook として接続します。
+
 ## Session
 
 ### Get Session
@@ -461,6 +632,7 @@ const auth = new AppsScriptAuth({
 - Sign In
 - Sign Up
 - Sign Out
+- Authentication lifecycle hooks (`afterSignIn`)
 - Session management
 - CacheService SessionStorage
 - PropertiesService SessionStorage

package/dist/AppsScriptAuth.d.ts

@@ -6,6 +6,7 @@ import { AppsScriptAuthSignUp } from "./api/AppsScriptAuthSignUp";
 import { type AppsScriptAuthenticationOptions } from "./authentication/AppsScriptAuthentication";
 import { type EmailPasswordAuthOptions } from "./authentication/EmailPasswordAuthentication";
 import type { SessionStorageType } from "./factory/sessionStorageFactory";
+import type { AuthHooks } from "./hooks/AuthHooks";
 import { AppsScriptAuthRepository } from "./storage/AppsScriptAuthRepository";
 type SessionConfig = {
     storageType: SessionStorageType;
@@ -17,16 +18,17 @@ type AppsScriptRuntime = {
     cacheService: GoogleAppsScript.Cache.CacheService;
     propertiesService: GoogleAppsScript.Properties.PropertiesService;
 };
-type AppsScriptAuthConfig<TEmailPassword extends EmailPasswordAuthOptions | undefined = undefined> = {
+type AppsScriptAuthConfig<TEmailPassword extends EmailPasswordAuthOptions | undefined = undefined, THookResult = undefined> = {
     repository: AppsScriptAuthRepository;
     session: SessionConfig;
     runtime: AppsScriptRuntime;
     emailPassword?: TEmailPassword;
     appsScript?: AppsScriptAuthenticationOptions;
+    hooks?: AuthHooks<THookResult>;
 };
-type BaseHandlers = {
-    signInEmail: AppsScriptAuthSignIn["email"];
-    signInAppsScript: AppsScriptAuthSignIn["appsScript"];
+type BaseHandlers<THookResult> = {
+    signInEmail: AppsScriptAuthSignIn<THookResult>["email"];
+    signInAppsScript: AppsScriptAuthSignIn<THookResult>["appsScript"];
     signUpEmail: AppsScriptAuthSignUp["email"];
     signUpAppsScript: AppsScriptAuthSignUp["appsScript"];
     getSession: AppsScriptAuthSession["get"];
@@ -36,16 +38,16 @@ type PasswordHandlers = {
     forgotPassword: AppsScriptAuthPassword["forgot"];
     resetPassword: AppsScriptAuthPassword["reset"];
 };
-type AppsScriptAuthHandlers<TEmailPassword> = TEmailPassword extends {
+type AppsScriptAuthHandlers<TEmailPassword, THookResult> = TEmailPassword extends {
     passwordReset: unknown;
-} ? BaseHandlers & PasswordHandlers : BaseHandlers;
-export declare class AppsScriptAuth<TEmailPassword extends EmailPasswordAuthOptions | undefined = undefined> {
-    readonly signIn: AppsScriptAuthSignIn;
+} ? BaseHandlers<THookResult> & PasswordHandlers : BaseHandlers<THookResult>;
+export declare class AppsScriptAuth<TEmailPassword extends EmailPasswordAuthOptions | undefined = undefined, THookResult = undefined> {
+    readonly signIn: AppsScriptAuthSignIn<THookResult>;
     readonly signUp: AppsScriptAuthSignUp;
     readonly session: AppsScriptAuthSession;
     readonly signOut: AppsScriptAuthSignOut;
     readonly password: AppsScriptAuthPassword | undefined;
-    constructor({ repository, session, runtime, emailPassword, appsScript, }: AppsScriptAuthConfig<TEmailPassword>);
-    get handlers(): AppsScriptAuthHandlers<TEmailPassword>;
+    constructor({ repository, session, runtime, emailPassword, appsScript, hooks, }: AppsScriptAuthConfig<TEmailPassword, THookResult>);
+    get handlers(): AppsScriptAuthHandlers<TEmailPassword, THookResult>;
 }
 export {};

package/dist/AppsScriptAuth.js

@@ -12,7 +12,7 @@ export class AppsScriptAuth {
     session;
     signOut;
     password;
-    constructor({ repository, session, runtime, emailPassword, appsScript, }) {
+    constructor({ repository, session, runtime, emailPassword, appsScript, hooks, }) {
         const sessionStorage = sessionStorageFactory(session.storageType, {
             cacheService: runtime.cacheService,
             propertiesService: runtime.propertiesService,
@@ -32,6 +32,11 @@ export class AppsScriptAuth {
             utilities: runtime.utilities,
             session: runtime.session,
             expiresIn,
+            ...(hooks?.afterSignIn
+                ? {
+                    afterSignIn: hooks.afterSignIn,
+                }
+                : {}),
         });
         this.signUp = new AppsScriptAuthSignUp({
             sessionStorage,

package/dist/api/AppsScriptAuthSignIn.d.ts

@@ -2,13 +2,14 @@ import type { AppsScriptAuthenticationConfig } from "../authentication/AppsScrip
 import { type AppsScriptCredential } from "../authentication/AppsScriptAuthentication";
 import type { EmailPasswordAuthConfig } from "../authentication/EmailPasswordAuthentication";
 import { type EmailPasswordCredential } from "../authentication/EmailPasswordAuthentication";
+import type { AfterSignInHook } from "../hooks/AuthHooks";
 import { AppsScriptAuthRepository } from "../storage/AppsScriptAuthRepository";
 import { AppsScriptSessionStorage } from "../storage/AppsScriptSessionStorage";
 import { SignIn } from "./SignIn";
-export declare class AppsScriptAuthSignIn {
-    email: SignIn<EmailPasswordCredential>["execute"];
-    appsScript: SignIn<AppsScriptCredential>["execute"];
-    constructor({ sessionStorage, expiresIn, repository, emailPassword, appsScript, session, utilities, }: {
+export declare class AppsScriptAuthSignIn<THookResult = undefined> {
+    email: SignIn<EmailPasswordCredential, THookResult>["execute"];
+    appsScript: SignIn<AppsScriptCredential, THookResult>["execute"];
+    constructor({ sessionStorage, expiresIn, repository, emailPassword, appsScript, session, utilities, afterSignIn, }: {
         sessionStorage: AppsScriptSessionStorage;
         repository: AppsScriptAuthRepository;
         emailPassword?: EmailPasswordAuthConfig;
@@ -16,5 +17,6 @@ export declare class AppsScriptAuthSignIn {
         utilities: GoogleAppsScript.Utilities.Utilities;
         session: GoogleAppsScript.Base.Session;
         expiresIn: number;
+        afterSignIn?: AfterSignInHook<THookResult>;
     });
 }

package/dist/api/AppsScriptAuthSignIn.js

@@ -4,7 +4,7 @@ import { SignIn } from "./SignIn";
 export class AppsScriptAuthSignIn {
     email;
     appsScript;
-    constructor({ sessionStorage, expiresIn, repository, emailPassword, appsScript, session, utilities, }) {
+    constructor({ sessionStorage, expiresIn, repository, emailPassword, appsScript, session, utilities, afterSignIn, }) {
         this.email = async (credential) => {
             if (!emailPassword) {
                 throw new Error("Email and password authentication is disabled");
@@ -15,6 +15,11 @@ export class AppsScriptAuthSignIn {
                 authentication: new EmailPasswordAuthentication(repository, utilities, emailPassword),
                 utilities,
                 expiresIn,
+                ...(afterSignIn
+                    ? {
+                        afterSignIn,
+                    }
+                    : {}),
             });
             return emailSignIn.execute(credential);
         };
@@ -28,6 +33,11 @@ export class AppsScriptAuthSignIn {
                 authentication: new AppsScriptAuthentication(repository, session),
                 utilities,
                 expiresIn,
+                ...(afterSignIn
+                    ? {
+                        afterSignIn,
+                    }
+                    : {}),
             }).execute(credential);
         };
     }

package/dist/api/SignIn.d.ts

@@ -1,19 +1,30 @@
 import { Authentication } from "../authentication/Authentication";
 import { Session } from "../domain/Session";
+import type { User } from "../domain/User";
+import type { AfterSignInHook } from "../hooks/AuthHooks";
 import type { AppsScriptSessionStorage } from "../storage/AppsScriptSessionStorage";
-export declare class SignIn<T> {
+export type SignInResult<THookResult = undefined> = [THookResult] extends [
+    undefined
+] ? {
+    readonly user: User;
+    readonly session: Session;
+} : {
+    readonly user: User;
+    readonly session: Session;
+    readonly hooks: THookResult;
+};
+export declare class SignIn<TCredential, THookResult = undefined> {
     private readonly sessionStorage;
     private readonly expiresIn;
     private readonly utilities;
     private readonly authentication;
-    constructor({ sessionStorage, authentication, utilities, expiresIn, }: {
+    private readonly afterSignIn;
+    constructor({ sessionStorage, authentication, utilities, expiresIn, afterSignIn, }: {
         sessionStorage: AppsScriptSessionStorage;
-        authentication: Authentication<T>;
+        authentication: Authentication<TCredential>;
         utilities: GoogleAppsScript.Utilities.Utilities;
         expiresIn: number;
+        afterSignIn?: AfterSignInHook<THookResult>;
     });
-    execute(credential: T): Promise<{
-        user: import("..").User;
-        session: Session;
-    }>;
+    execute(credential: TCredential): Promise<SignInResult<THookResult>>;
 }

package/dist/api/SignIn.js

@@ -4,15 +4,15 @@ export class SignIn {
     expiresIn;
     utilities;
     authentication;
-    constructor({ sessionStorage, authentication, utilities, expiresIn, }) {
-        // Initialize SignIn with db, schema, and session
+    afterSignIn;
+    constructor({ sessionStorage, authentication, utilities, expiresIn, afterSignIn, }) {
         this.sessionStorage = sessionStorage;
         this.authentication = authentication;
         this.utilities = utilities;
         this.expiresIn = expiresIn;
+        this.afterSignIn = afterSignIn;
     }
     async execute(credential) {
-        // Implement the sign-in logic using the provided authentication method
         const user = await this.authentication.verify(credential);
         const session = new Session({
             id: this.utilities.getUuid(),
@@ -21,6 +21,32 @@ export class SignIn {
             expiresAt: new Date(Date.now() + this.expiresIn),
         });
         await this.sessionStorage.save(session);
-        return { user, session };
+        if (!this.afterSignIn) {
+            return {
+                user,
+                session,
+            };
+        }
+        const context = {
+            user,
+            session,
+        };
+        try {
+            const hooks = await this.afterSignIn(context);
+            return {
+                user,
+                session,
+                hooks,
+            };
+        }
+        catch (error) {
+            try {
+                await this.sessionStorage.delete(session.id);
+            }
+            catch {
+                // Preserve the original hook error.
+            }
+            throw error;
+        }
     }
 }

package/dist/hooks/AuthHooks.d.ts

@@ -0,0 +1,10 @@
+import type { Session } from "../domain/Session";
+import type { User } from "../domain/User";
+export type AfterSignInContext = {
+    readonly user: User;
+    readonly session: Session;
+};
+export type AfterSignInHook<TResult> = (context: AfterSignInContext) => TResult | Promise<TResult>;
+export type AuthHooks<TResult = undefined> = {
+    readonly afterSignIn?: AfterSignInHook<TResult>;
+};

package/dist/hooks/AuthHooks.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export { PasswordCredential } from "./domain/PasswordCredential";
 export { PasswordReset } from "./domain/PasswordReset";
 export { AppsScriptIdentity } from "./identity/AppsScriptIdentity";
 export { EmailPasswordIdentity } from "./identity/EmailPasswordIdentity";
+export type { AfterSignInContext, AfterSignInHook, AuthHooks, } from "./hooks/AuthHooks";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasboost/auth",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Modern authentication for Google Apps Script with email/password, Apps Script authentication, sessions, and password reset.",
   "keywords": [
     "google-apps-script",