@causa/workspace-google 0.1.1 → 0.2.0

package/dist/functions/google-identity-platform-generate-token.js

@@ -0,0 +1,74 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { CliArgument, CliCommand, CliOption } from '@causa/cli';
+import { WorkspaceFunction } from '@causa/workspace';
+import { AllowMissing } from '@causa/workspace/validation';
+import { Transform } from 'class-transformer';
+import { IsObject, IsString } from 'class-validator';
+import { getAuth, signInWithCustomToken } from 'firebase/auth';
+import { identityPlatformCommandDefinition } from '../cli/index.js';
+import { FirebaseAppService } from '../services/index.js';
+import { GoogleIdentityPlatformGenerateCustomToken } from './google-identity-platform-generate-custom-token.js';
+/**
+ * Generates an ID token for an Identity Platform end user.
+ * For this function to succeed, the `google.project` should be set, which usually means setting the environment in the
+ * context. Also `google.firebase` children can be used to configure (and speed up) how tokens are generated.
+ */
+let GoogleIdentityPlatformGenerateToken = class GoogleIdentityPlatformGenerateToken extends WorkspaceFunction {
+    /**
+     * The ID of the user for which the token will be generated.
+     */
+    user;
+    /**
+     * A dictionary of custom claims that will be added to the generated JWT.
+     */
+    claims;
+    async _call(context) {
+        context.logger.info(`🛂 Signing in user '${this.user}' with a custom token.`);
+        const customToken = await context.call(GoogleIdentityPlatformGenerateCustomToken, { user: this.user, claims: this.claims });
+        const app = await context.service(FirebaseAppService).getApp();
+        const auth = getAuth(app);
+        const credentials = await signInWithCustomToken(auth, customToken);
+        return await credentials.user.getIdToken();
+    }
+    _supports() {
+        return true;
+    }
+};
+__decorate([
+    CliArgument({
+        name: '<user>',
+        position: 0,
+        description: 'The ID of the user for which the token will be generated.',
+    }),
+    IsString(),
+    __metadata("design:type", String)
+], GoogleIdentityPlatformGenerateToken.prototype, "user", void 0);
+__decorate([
+    CliOption({
+        flags: '-c, --claims <claims>',
+        description: 'A JSON string containing custom claims that will be added to the token.',
+    }),
+    IsObject(),
+    AllowMissing(),
+    Transform(({ value }) => typeof value === 'string' ? JSON.parse(value) : value),
+    __metadata("design:type", Object)
+], GoogleIdentityPlatformGenerateToken.prototype, "claims", void 0);
+GoogleIdentityPlatformGenerateToken = __decorate([
+    CliCommand({
+        parent: identityPlatformCommandDefinition,
+        name: 'genToken',
+        description: `Generates an ID token that can be used to access Firebase services as an end user.
+Optional custom claims can be included in the signed token.`,
+        summary: 'Generates an ID token that can be used to access Firebase services as a client.',
+        outputFn: (token) => console.log(token),
+    })
+], GoogleIdentityPlatformGenerateToken);
+export { GoogleIdentityPlatformGenerateToken };

package/dist/functions/google-spanner-list-databases.d.ts

@@ -0,0 +1,33 @@
+import { WorkspaceContext, WorkspaceFunction } from '@causa/workspace';
+/**
+ * The definition of a Spanner database with its DDL statements.
+ */
+export type SpannerDatabase = {
+    /**
+     * The ID / name of the database.
+     */
+    id: string;
+    /**
+     * The paths (relative to the workspace root) containing DDL statements for this database.
+     */
+    ddlFiles: string[];
+    /**
+     * The DDL statements for the database.
+     */
+    ddls: string[];
+};
+/**
+ * A function that lists Spanner databases defined in the workspace, and returns their corresponding DDLs.
+ */
+export declare class GoogleSpannerListDatabases extends WorkspaceFunction<Promise<SpannerDatabase[]>> {
+    _call(context: WorkspaceContext): Promise<SpannerDatabase[]>;
+    /**
+     * Parses a SQL file containing Spanner DDL statements.
+     * End-of-the-line comments are removed, and statements are split using semicolons.
+     *
+     * @param path The path to the SQL file containing DDL statements.
+     * @returns The list of DDL statements.
+     */
+    private parseDdlFile;
+    _supports(): boolean;
+}

package/dist/functions/google-spanner-list-databases.js

@@ -0,0 +1,66 @@
+import { WorkspaceFunction, listFilesAndFormat, } from '@causa/workspace';
+import { readFile } from 'fs/promises';
+/**
+ * The default format used to infer the ID / name of the database from the format parts.
+ */
+const DEFAULT_DDL_DATABASE_ID_FORMAT = '${ database }';
+/**
+ * The default glob pattern used to find DDL statements in the workspace.
+ */
+const DEFAULT_DDL_GLOBS = ['domains/*/spanner/*.sql'];
+/**
+ * The default regular expression used to extract format parts from DDL file paths.
+ */
+const DEFAULT_DDL_REGULAR_EXPRESSION = 'domains/(?<database>[\\w-]+)\\/spanner\\/[\\w-]+\\.sql';
+/**
+ * A function that lists Spanner databases defined in the workspace, and returns their corresponding DDLs.
+ */
+export class GoogleSpannerListDatabases extends WorkspaceFunction {
+    async _call(context) {
+        const googleConf = context.asConfiguration();
+        const format = googleConf.get('google.spanner.ddls.format') ??
+            DEFAULT_DDL_DATABASE_ID_FORMAT;
+        const globs = googleConf.get('google.spanner.ddls.globs') ?? DEFAULT_DDL_GLOBS;
+        const regExp = googleConf.get('google.spanner.ddls.regularExpression') ??
+            DEFAULT_DDL_REGULAR_EXPRESSION;
+        context.logger.debug('🗃️ Listing Spanner databases and DDL files.');
+        const filesAndFormats = await listFilesAndFormat(globs, regExp, format, context.rootPath, {
+            nonMatchingPathHandler: (path) => context.logger.warn(`📂 Path '${path}' matches the Spanner DDL globs but did not match the regular expression. It will be ignored.`),
+        });
+        const databaseDdlFiles = filesAndFormats.reduce((files, { rendered, filePath }) => {
+            (files[rendered] ?? (files[rendered] = [])).push(filePath);
+            return files;
+        }, {});
+        return await Promise.all(Object.entries(databaseDdlFiles).map(async ([id, ddlFiles]) => {
+            ddlFiles.sort();
+            const ddlsInFiles = await Promise.all(ddlFiles.map((ddlFile) => this.parseDdlFile(ddlFile)));
+            const ddls = ddlsInFiles.flatMap((ddls) => ddls);
+            context.logger.debug(`🗃️ Found Spanner database '${id}' with ${ddlFiles.length} DDL file(s) and ${ddls.length} statement(s).`);
+            return { id, ddlFiles, ddls };
+        }));
+    }
+    /**
+     * Parses a SQL file containing Spanner DDL statements.
+     * End-of-the-line comments are removed, and statements are split using semicolons.
+     *
+     * @param path The path to the SQL file containing DDL statements.
+     * @returns The list of DDL statements.
+     */
+    async parseDdlFile(path) {
+        const rawFile = (await readFile(path)).toString();
+        return (rawFile
+            // Removing comments using the `-- My comment until the end of the line` syntax.
+            .replace(/--.*$/gm, '')
+            // Trimming lines for readability in logs, and joining them to easily split into statements.
+            .split('\n')
+            .map((statement) => statement.trim())
+            .join(' ')
+            // Splitting the SQL statements.
+            .split(';')
+            // Trimming for readability in logs.
+            .map((statement) => statement.trim()));
+    }
+    _supports() {
+        return true;
+    }
+}

package/dist/functions/index.js

@@ -1,7 +1,22 @@
+import { EmulatorStartForFirebaseStorage } from './emulator-start-firebase-storage.js';
+import { EmulatorStartForFirestore } from './emulator-start-firestore.js';
+import { EmulatorStartForIdentityPlatform } from './emulator-start-identity-platform.js';
+import { EmulatorStartForPubSub } from './emulator-start-pubsub.js';
+import { EmulatorStartForSpanner } from './emulator-start-spanner.js';
+import { EmulatorStopForFirebaseStorage } from './emulator-stop-firebase-storage.js';
+import { EmulatorStopForFirestore } from './emulator-stop-firestore.js';
+import { EmulatorStopForIdentityPlatform } from './emulator-stop-identity-platform.js';
+import { EmulatorStopForPubSub } from './emulator-stop-pubsub.js';
+import { EmulatorStopForSpanner } from './emulator-stop-spanner.js';
+import { GoogleAppCheckGenerateToken } from './google-app-check-generate-token.js';
 import { GoogleFirebaseStorageMergeRules } from './google-firebase-storage-merge-rules.js';
 import { GoogleFirestoreMergeRules } from './google-firestore-merge-rules.js';
+import { GoogleIdentityPlatformGenerateCustomToken } from './google-identity-platform-generate-custom-token.js';
+import { GoogleIdentityPlatformGenerateToken } from './google-identity-platform-generate-token.js';
 import { GoogleServicesEnable } from './google-services-enable.js';
+import { GoogleSpannerListDatabases } from './google-spanner-list-databases.js';
+import { ProjectGetArtefactDestinationForServiceContainer } from './project-get-artefact-destination-service-container.js';
 import { SecretFetchForGoogleSecretManager } from './secret-fetch-secret-manager.js';
 export function registerFunctions(context) {
-    context.registerFunctionImplementations(GoogleFirebaseStorageMergeRules, GoogleFirestoreMergeRules, GoogleServicesEnable, SecretFetchForGoogleSecretManager);
+    context.registerFunctionImplementations(EmulatorStartForFirebaseStorage, EmulatorStartForFirestore, EmulatorStartForIdentityPlatform, EmulatorStartForPubSub, EmulatorStartForSpanner, EmulatorStopForFirebaseStorage, EmulatorStopForFirestore, EmulatorStopForIdentityPlatform, EmulatorStopForPubSub, EmulatorStopForSpanner, GoogleAppCheckGenerateToken, GoogleFirebaseStorageMergeRules, GoogleFirestoreMergeRules, GoogleIdentityPlatformGenerateCustomToken, GoogleIdentityPlatformGenerateToken, GoogleServicesEnable, GoogleSpannerListDatabases, ProjectGetArtefactDestinationForServiceContainer, SecretFetchForGoogleSecretManager);
 }

package/dist/functions/project-get-artefact-destination-service-container.d.ts

@@ -0,0 +1,10 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { ProjectGetArtefactDestination } from '@causa/workspace-core';
+/**
+ * Implements the {@link ProjectGetArtefactDestination} function for Cloud Run services.
+ * The destination Docker repository is expected to be defined in `google.cloudRun.dockerRepository`.
+ */
+export declare class ProjectGetArtefactDestinationForServiceContainer extends ProjectGetArtefactDestination {
+    _call(context: WorkspaceContext): Promise<string>;
+    _supports(context: WorkspaceContext): boolean;
+}

package/dist/functions/project-get-artefact-destination-service-container.js

@@ -0,0 +1,17 @@
+import { ProjectGetArtefactDestination, } from '@causa/workspace-core';
+/**
+ * Implements the {@link ProjectGetArtefactDestination} function for Cloud Run services.
+ * The destination Docker repository is expected to be defined in `google.cloudRun.dockerRepository`.
+ */
+export class ProjectGetArtefactDestinationForServiceContainer extends ProjectGetArtefactDestination {
+    async _call(context) {
+        const projectName = context.getOrThrow('project.name');
+        const dockerRepository = context.getOrThrow('google.cloudRun.dockerRepository');
+        return `${dockerRepository}/${projectName}:${this.tag}`;
+    }
+    _supports(context) {
+        const conf = context.asConfiguration();
+        return (conf.get('project.type') === 'serviceContainer' &&
+            conf.get('serviceContainer.platform') === 'google.cloudRun');
+    }
+}

package/dist/services/firebase-app.d.ts

@@ -0,0 +1,151 @@
+import { WorkspaceContext } from '@causa/workspace';
+import { App as FirebaseAdminApp } from 'firebase-admin/app';
+import { FirebaseApp } from 'firebase/app';
+/**
+ * The types (platforms) of Firebase apps.
+ * Apps are split by type and cannot be listed globally.
+ */
+declare const FIREBASE_APP_TYPES: readonly ["androidApps", "iosApps", "webApps"];
+/**
+ * The type (platform) of a Firebase app.
+ */
+export type FirebaseAppType = (typeof FIREBASE_APP_TYPES)[number];
+/**
+ * A service exposing generic Firebase functionalities based on the workspace configuration.
+ */
+export declare class FirebaseAppService {
+    /**
+     * The GCP project ID read from the {@link WorkspaceContext} configuration.
+     */
+    readonly projectId: string;
+    /**
+     * The Firebase auth domain, read from the configuration or inferred from the GCP project ID.
+     */
+    readonly authDomain: string;
+    /**
+     * The logger to use.
+     */
+    private readonly logger;
+    /**
+     * The Firebase API key set in the configuration.
+     * This could be `undefined`, in which case {@link FirebaseAppService.findApiKey} will be called.
+     */
+    private readonly confApiKey;
+    /**
+     * The Firebase admin service account for the GCP project, read from the configuration.
+     * This could be `undefined`, in which case {@link FirebaseAppService.findAdminServiceAccount} will be called.
+     */
+    private readonly confAdminServiceAccount;
+    /**
+     * The Firebase app ID, read from the configuration.
+     * This could be `undefined`, in which case {@link FirebaseAppService.getAnyAppId} will be called.
+     */
+    private readonly confAppId;
+    /**
+     * The {@link GoogleApisService} used to make calls to IAM when listing service accounts.
+     */
+    private readonly googleApisService;
+    constructor(context: WorkspaceContext);
+    /**
+     * The promise resolving to the Firebase API key, in the case it wasn't set in the configuration.
+     */
+    private apiKeyPromise;
+    /**
+     * Finds a Firebase API key for the configured GCP project by listing them using the API keys API.
+     * The method used to find the correct API key is a hack, relying on the display name of the key.
+     * This is why it is preferable for the API key to be set manually in the configuration.
+     *
+     * @returns A Firebase API key for the configured GCP project.
+     */
+    private findApiKey;
+    /**
+     * Returns either the Firebase API key set in the configuration, or one found using the Google APIs.
+     *
+     * @returns The Firebase API key.
+     */
+    getApiKey(): Promise<string>;
+    /**
+     * The singleton {@link FirebaseApp} created by {@link FirebaseAppService.getApp}.
+     */
+    private app;
+    /**
+     * Initializes and returns a {@link FirebaseApp} for the configured GCP project.
+     *
+     * @returns The {@link FirebaseApp}.
+     */
+    getApp(): Promise<FirebaseApp>;
+    /**
+     * The promise resolving to the email of the Firebase-owned service account, in case it wasn't set in the
+     * configuration.
+     */
+    private adminServiceAccountPromise;
+    /**
+     * Looks for the automatically-created Firebase admin service account by listing service accounts in the configured
+     * GCP project.
+     * This is a hack which uses the inferred format of the service account name used by Firebase. It is preferred to
+     * manually set the `google.firebase.adminServiceAccount` configuration.
+     *
+     * @returns The email of the Firebase admin service account.
+     */
+    private findAdminServiceAccount;
+    /**
+     * Returns the email for the Firebase admin service account, either from the configuration or by listing service
+     * accounts using Google APIs.
+     *
+     * @returns The email for the Firebase admin service account.
+     */
+    getAdminServiceAccount(): Promise<string>;
+    /**
+     * The singleton {@link FirebaseAdminApp}, created by {@link FirebaseAppService.getAdminAppForAdminServiceAccount}.
+     */
+    private adminAppForAdminServiceAccount;
+    /**
+     * Returns a Firebase admin app configured to authenticate as the Firebase admin service account.
+     * Using a service account rather than end user credentials ensures access to all functionalities (e.g. token
+     * signing), which are otherwise unavailable to end users.
+     *
+     * @returns The Firebase admin app.
+     */
+    getAdminAppForAdminServiceAccount(): Promise<FirebaseAdminApp>;
+    /**
+     * Creates a {@link Credential} object that can be used when initializing a Firebase admin app.
+     * The returned object generates access tokens for the given service account. The application default credentials (or
+     * any other default authentication method) should provide authorization to sign tokens in the GCP project for this to
+     * work.
+     *
+     * @param serviceAccountId The ID / email of the service account to impersonate.
+     * @returns The {@link Credential} to use with the Firebase admin app.
+     */
+    private makeAdminCredential;
+    /**
+     * Looks for a Firebase app ID using the API and returns the first one found.
+     * This could be the ID of an Android, iOS, or web app.
+     * If no app can be found, an error is returned.
+     *
+     * @param options Options when listing the existing apps.
+     * @returns The first found Firebase app ID.
+     */
+    getAnyAppId(options?: {
+        appTypes?: FirebaseAppType[];
+    }): Promise<string>;
+    /**
+     * Fetches the first Firebase app of a given type and returns its ID.
+     *
+     * @param client The Firebase API client to use.
+     * @param appType The type of Firebase app to list.
+     * @returns The ID of the first app, or `null` if none could be found.
+     */
+    private getFirstApp;
+    /**
+     * The promise resolving to one of the Firebase App IDs available in the GCP project.
+     * Only set if {@link FirebaseAppService.confAppId} is not set.
+     */
+    private appIdPromise;
+    /**
+     * Returns the Firebase App ID, either from the configuration or by listing apps using Google APIs.
+     *
+     * @returns The Firebase App ID.
+     */
+    getAppId(): Promise<string>;
+}
+export {};

package/dist/services/firebase-app.errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The base class for errors in the FirebaseApp service.
+ */
+export declare class FirebaseAppServiceError extends Error {
+}
+/**
+ * An error thrown when the Firebase admin service account cannot be found in the configured GCP project.
+ */
+export declare class FirebaseAdminServiceAccountNotFoundError extends FirebaseAppServiceError {
+    readonly projectId: string;
+    constructor(projectId: string);
+}
+/**
+ * An error thrown when a Firebase API key cannot be found in the configured GCP project.
+ */
+export declare class FirebaseApiKeyNotFoundError extends FirebaseAppServiceError {
+    readonly projectId: string;
+    constructor(projectId: string);
+}
+/**
+ * An error thrown when no Firebase app can be found in the given GCP project.
+ */
+export declare class NoFirebaseAppFoundError extends FirebaseAppServiceError {
+    readonly projectId: string;
+    constructor(projectId: string);
+}

package/dist/services/firebase-app.errors.js

@@ -0,0 +1,35 @@
+/**
+ * The base class for errors in the FirebaseApp service.
+ */
+export class FirebaseAppServiceError extends Error {
+}
+/**
+ * An error thrown when the Firebase admin service account cannot be found in the configured GCP project.
+ */
+export class FirebaseAdminServiceAccountNotFoundError extends FirebaseAppServiceError {
+    projectId;
+    constructor(projectId) {
+        super(`Unable to find the service account for Firebase admin from the list of accounts in project '${projectId}'.`);
+        this.projectId = projectId;
+    }
+}
+/**
+ * An error thrown when a Firebase API key cannot be found in the configured GCP project.
+ */
+export class FirebaseApiKeyNotFoundError extends FirebaseAppServiceError {
+    projectId;
+    constructor(projectId) {
+        super(`Unable to find a Firebase API key from the keys listed in project '${projectId}'.`);
+        this.projectId = projectId;
+    }
+}
+/**
+ * An error thrown when no Firebase app can be found in the given GCP project.
+ */
+export class NoFirebaseAppFoundError extends FirebaseAppServiceError {
+    projectId;
+    constructor(projectId) {
+        super(`Unable to find a single Firebase app in project '${projectId}' using the API.`);
+        this.projectId = projectId;
+    }
+}