@my-f-startup/google-internal-auth 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 My F* Startup
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @my-f-startup/google-internal-auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Authentication of internal calls between Google Cloud services.
+
+A Cloud Run service often has routes that only another Google service may call: a job triggered by Cloud Scheduler, a Pub/Sub push subscription, another service. Those callers send an ID token issued by Google for the service account they run as, with the URL of the target service as audience. This package accepts a request only when that token is valid for the audience of the service and its verified email is in the list of allowed callers.
+
+---
+
+## Why this exists
+
+Cloud Run services that sit behind a gateway such as Firebase Hosting must accept requests at the platform level, so the platform does not check who calls an internal route. Each service checks it itself. The Google auth library verifies the signature and the audience of the token; the rest is the same in every service: read the bearer token, require the verified email of an allowed caller, reject everything when nothing is configured, read the configuration from the environment, and skip the check against the emulators, where no Google token exists. This package holds that once.
+
+---
+
+## Features
+
+- ✅ **Signature and audience** – verified by the Google auth library
+- ✅ **Allowed callers** – the verified email of the token must be in the list
+- ✅ **Closed by default** – without an audience or allowed callers, every request is rejected
+- ✅ **Environment configuration** – `INTERNAL_ALLOWED_CALLERS` and `INTERNAL_AUDIENCE`
+- ✅ **Local development** – the check is skipped when an emulator host is configured
+- ✅ **Two shapes** – a function that answers `true` or `false`, usable as an OpenAPI security handler, and an Express style middleware
+
+---
+
+## Installation
+
+```bash
+npm install @my-f-startup/google-internal-auth
+```
+
+---
+
+## Quick Start
+
+As the security handler of an OpenAPI validator (for example `express-openapi-validator`):
+
+```ts
+import {
+  createInternalAuthHandler,
+  internalAuthOptionsFromEnvironment,
+} from "@my-f-startup/google-internal-auth";
+
+const validateSecurity = {
+  handlers: {
+    internalAuth: createInternalAuthHandler(internalAuthOptionsFromEnvironment()),
+  },
+};
+```
+
+As an Express middleware:
+
+```ts
+import { internalAuthMiddleware, internalAuthOptionsFromEnvironment } from "@my-f-startup/google-internal-auth";
+
+app.post("/internal/jobs/publish-outbox", internalAuthMiddleware(internalAuthOptionsFromEnvironment()), handler);
+```
+
+---
+
+## API
+
+### `createInternalAuthHandler(options)`
+
+Returns `(req) => Promise<boolean>`. A request is accepted when it has `Authorization: Bearer <token>`, the token is valid for `audience`, and its email is verified and listed in `allowedCallers`.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `allowedCallers` | `string[]` | Emails of the service accounts allowed to call. Empty rejects every request |
+| `audience` | `string` | Audience the token must be issued for: the URL of the service. Missing rejects every request |
+| `skip` | `boolean` | Accept every request, for local development |
+| `verifier` | `IdTokenVerifier` | Verifies the token. Defaults to the `OAuth2Client` of the Google auth library; tests pass a fake |
+
+### `internalAuthOptionsFromEnvironment(environment?)`
+
+Reads `INTERNAL_ALLOWED_CALLERS` (comma separated emails) and `INTERNAL_AUDIENCE`. `skip` is `true` when `FIRESTORE_EMULATOR_HOST`, `FIREBASE_DATABASE_EMULATOR_HOST`, `FIREBASE_AUTH_EMULATOR_HOST` or `PUBSUB_EMULATOR_HOST` is set.
+
+### `internalAuthMiddleware(options)`
+
+Calls `next()` for an accepted request and answers 401 otherwise.
+
+---
+
+## Tests
+
+- Unit: `npm run test:unit`
+- All tests: `npm test`
+
+The check against a real token issued by Google runs only in a deployed environment.
+
+---
+
+## Compatibility
+
+- Node.js: >= 20
+
+---
+
+## Changelog
+
+The [CHANGELOG.md](CHANGELOG.md) file is **automatically generated** during pull requests from Conventional Commits (`feat`, `fix`, `refactor`, `perf`). Do not edit it manually.
+
+---
+
+Made with ❤️ by My F* Startup

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createInternalAuthHandler, internalAuthMiddleware, internalAuthOptionsFromEnvironment } from "./internalAuth";
+export type { IdTokenVerifier, InternalAuthOptions, RequestWithHeaders } from "./internalAuth";
+//# 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":"AAAA,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,kCAAkC,EAAE,MAAM,gBAAgB,CAAC;AAEvH,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.internalAuthOptionsFromEnvironment = exports.internalAuthMiddleware = exports.createInternalAuthHandler = void 0;
+var internalAuth_1 = require("./internalAuth");
+Object.defineProperty(exports, "createInternalAuthHandler", { enumerable: true, get: function () { return internalAuth_1.createInternalAuthHandler; } });
+Object.defineProperty(exports, "internalAuthMiddleware", { enumerable: true, get: function () { return internalAuth_1.internalAuthMiddleware; } });
+Object.defineProperty(exports, "internalAuthOptionsFromEnvironment", { enumerable: true, get: function () { return internalAuth_1.internalAuthOptionsFromEnvironment; } });

package/dist/internalAuth.d.ts

@@ -0,0 +1,52 @@
+export type IdTokenVerifier = {
+    verifyIdToken: (options: {
+        idToken: string;
+        audience: string;
+    }) => Promise<{
+        getPayload: () => {
+            email?: string;
+            email_verified?: boolean;
+        } | undefined;
+    }>;
+};
+export type InternalAuthOptions = {
+    /** Emails of the service accounts allowed to call the internal routes. */
+    allowedCallers: readonly string[];
+    /** Audience the token must be issued for: the URL of the service. */
+    audience?: string;
+    /** Accept every request, for local development against emulators. */
+    skip?: boolean;
+    /** Verifies the token. Defaults to the Google auth library, which checks the signature and the audience. */
+    verifier?: IdTokenVerifier;
+};
+export type RequestWithHeaders = {
+    headers: {
+        authorization?: string;
+    };
+};
+/**
+ * Checks a request to an internal route, such as a job called by Cloud Scheduler: it must carry a
+ * bearer ID token issued by Google for `audience`, with the verified email of one of the
+ * `allowedCallers`. Without an audience or allowed callers every request is rejected.
+ *
+ * The returned function answers `true` or `false`, so it can be used as the security handler of an
+ * OpenAPI validator, or wrapped in a middleware with `internalAuthMiddleware`.
+ */
+export declare const createInternalAuthHandler: (options: InternalAuthOptions) => (req: RequestWithHeaders) => Promise<boolean>;
+/**
+ * Options from `INTERNAL_ALLOWED_CALLERS` (comma separated emails) and `INTERNAL_AUDIENCE`. The check
+ * is skipped when an emulator host is configured, since there is no Google issued token against the
+ * emulators.
+ */
+export declare const internalAuthOptionsFromEnvironment: (environment?: NodeJS.ProcessEnv) => InternalAuthOptions;
+type MiddlewareResponse = {
+    status: (code: number) => {
+        end: () => void;
+    };
+};
+/**
+ * Express style middleware: calls `next()` for an accepted request and answers 401 otherwise.
+ */
+export declare const internalAuthMiddleware: (options: InternalAuthOptions) => (req: RequestWithHeaders, res: MiddlewareResponse, next: (error?: unknown) => void) => void;
+export {};
+//# sourceMappingURL=internalAuth.d.ts.map

package/dist/internalAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internalAuth.d.ts","sourceRoot":"","sources":["../src/internalAuth.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,eAAe,GAAG;IAC5B,aAAa,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;QACzE,UAAU,EAAE,MAAM;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,cAAc,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,SAAS,CAAC;KAC5E,CAAC,CAAC;CACJ,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,0EAA0E;IAC1E,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4GAA4G;IAC5G,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC,CAAC;AASF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,mBAAmB,MAGtD,KAAK,kBAAkB,KAAG,OAAO,CAAC,OAAO,CAqBxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,GAC7C,cAAa,MAAM,CAAC,UAAwB,KAC3C,mBAOD,CAAC;AAEH,KAAK,kBAAkB,GAAG;IACxB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,GAAG,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CAC/C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,mBAAmB,MAGzD,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,KAAG,IAM7F,CAAC"}

package/dist/internalAuth.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.internalAuthMiddleware = exports.internalAuthOptionsFromEnvironment = exports.createInternalAuthHandler = void 0;
+const google_auth_library_1 = require("google-auth-library");
+const EMULATOR_VARIABLES = [
+    "FIRESTORE_EMULATOR_HOST",
+    "FIREBASE_DATABASE_EMULATOR_HOST",
+    "FIREBASE_AUTH_EMULATOR_HOST",
+    "PUBSUB_EMULATOR_HOST",
+];
+/**
+ * Checks a request to an internal route, such as a job called by Cloud Scheduler: it must carry a
+ * bearer ID token issued by Google for `audience`, with the verified email of one of the
+ * `allowedCallers`. Without an audience or allowed callers every request is rejected.
+ *
+ * The returned function answers `true` or `false`, so it can be used as the security handler of an
+ * OpenAPI validator, or wrapped in a middleware with `internalAuthMiddleware`.
+ */
+const createInternalAuthHandler = (options) => {
+    const verifier = options.verifier ?? new google_auth_library_1.OAuth2Client();
+    return async (req) => {
+        if (options.skip)
+            return true;
+        const { audience, allowedCallers } = options;
+        const header = req.headers.authorization;
+        if (!audience || allowedCallers.length === 0 || !header?.startsWith("Bearer ")) {
+            return false;
+        }
+        try {
+            const ticket = await verifier.verifyIdToken({
+                idToken: header.substring("Bearer ".length),
+                audience,
+            });
+            const payload = ticket.getPayload();
+            return Boolean(payload?.email_verified && payload.email && allowedCallers.includes(payload.email));
+        }
+        catch {
+            return false;
+        }
+    };
+};
+exports.createInternalAuthHandler = createInternalAuthHandler;
+/**
+ * Options from `INTERNAL_ALLOWED_CALLERS` (comma separated emails) and `INTERNAL_AUDIENCE`. The check
+ * is skipped when an emulator host is configured, since there is no Google issued token against the
+ * emulators.
+ */
+const internalAuthOptionsFromEnvironment = (environment = process.env) => ({
+    allowedCallers: (environment.INTERNAL_ALLOWED_CALLERS ?? "")
+        .split(",")
+        .map((caller) => caller.trim())
+        .filter(Boolean),
+    audience: environment.INTERNAL_AUDIENCE,
+    skip: EMULATOR_VARIABLES.some((name) => Boolean(environment[name])),
+});
+exports.internalAuthOptionsFromEnvironment = internalAuthOptionsFromEnvironment;
+/**
+ * Express style middleware: calls `next()` for an accepted request and answers 401 otherwise.
+ */
+const internalAuthMiddleware = (options) => {
+    const isAllowed = (0, exports.createInternalAuthHandler)(options);
+    return (req, res, next) => {
+        isAllowed(req).then((allowed) => (allowed ? next() : res.status(401).end()), (error) => next(error));
+    };
+};
+exports.internalAuthMiddleware = internalAuthMiddleware;

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@my-f-startup/google-internal-auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Authentication of internal calls between Google Cloud services: accepts a request only with an ID token issued by Google for the audience of the service and the verified email of an allowed caller.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:ts": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "test": "tsx --test --test-concurrency=1 test/**/*.spec.ts",
+    "test:unit": "tsx --test --test-concurrency=1 test/*.unit.spec.ts"
+  },
+  "keywords": [
+    "google-cloud",
+    "cloud-run",
+    "cloud-scheduler",
+    "authentication",
+    "id-token",
+    "oidc",
+    "service-to-service"
+  ],
+  "author": "My Fucking Startup",
+  "license": "MIT",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/my-f-startup/google-internal-auth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/my-f-startup/google-internal-auth/issues"
+  },
+  "homepage": "https://github.com/my-f-startup/google-internal-auth#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "google-auth-library": "^9.15.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^25.9.9",
+    "@typescript-eslint/eslint-plugin": "^8.72.1",
+    "@typescript-eslint/parser": "^8.72.1",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-plugin-prettier": "^5.5.7",
+    "globals": "^17.14.0",
+    "prettier": "^3.9.10",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3"
+  }
+}