firestore-polp

Firestore PoLP (Principle of Least Privilege)

This library provides a simple and secure way to interact with Firestore, adhering to the Principle of Least Privilege (PoLP). It allows you to read and write data to Firestore without exposing your Firebase service token credentials.

Why?

Firebase service tokens give complete access to your Firebase project and Firestore database. They should be avoided where possible, especially in untrusted environments (like Electron apps or CI/CD pipelines that may be used by untrusted parties).

These are the official alternatives and the reasons why they might be unsuitable for an untrusted environment in Node.JS/Electron:

• Firebase Admin SDK - This library requires a service account token which is not suitable for untrusted environments.
• Firebase Web SDK - This library is advertised as working in Node.js but auth is not persisted correctly which makes it unsuitable.

Unfortunately, the Firebase Node.js client library requires a service token and the firebase Web SDK doesn't work in a Node.js environment.

Features

• Secure interaction with Firestore
• Read and write operations
• Support for document updates with merge
• Automatic serialization and deserialization of Firestore data types
• Retry mechanism for failed requests

Installation

npm install firestore-polp

Usage

First, sign in using a custom token:

import { signInWithCustomToken } from 'firestore-polp'
const credentials = await signInWithCustomToken(
  'your-public-api-key',
  'users-custom-token'
)

Then, initialize the library with your project details:

import { initialize } from 'firestore-polp'
const app = initialize('your-project-id', credentials.idToken, {
  databaseId: 'your-database-id' // Optional, defaults to '(default)'
})

Expired id tokens can also be refreshed using the initial credentials:

import { refreshIdToken } from 'firestore-polp'
const updatedCredentials = await refreshIdToken(
  'your-public-api-key',
  credentials.refreshToken
)

// re-initialize the library
const app = initialize('your-project-id', updatedCredentials.idToken, {
  databaseId: 'your-database-id' // Optional, defaults to '(default)'
})

Reading a document

import { getDocument } from 'firestore-polp'
const document = await getDocument(app, ['collection', 'document-id'])
console.log(document)

Updating a Document with Merge

import { updateDocumentWithMerge } from 'firestore-polp'
const result = await updateDocumentWithMerge(
  app,
  ['collection', 'document-id'],
  { field1: 'new value', field2: 42 }
)
console.log(result)

Setting a document

import { setDocument } from 'firestore-polp'
const result = await setDocument(app, ['collection', 'document-id'], {
  field1: 'value',
  field2: true
})
console.log(result)

API Reference

signInWithCustomToken(apiKey: string, customToken: string): Promise<SignInResponse>

Signs in with a custom token.

refreshIdToken(apiKey: string, refreshToken: string ): Promise<RefreshTokenResponse>

Refreshes an id token using an existing refresh token.

initialize(projectId: string, accessToken: string, options?: { databaseId: string }): AppConfig

Initializes the library with your project details.

getDocument<T>(config: AppConfig, documentPath: string[]): Promise<T>

Retrieves a document from Firestore.

updateDocumentWithMerge(config: AppConfig, documentPath: string[], fields: PlainData): Promise<UpdateDocumentResponse>

Updates a document with a merge operation.

setDocument(config: AppConfig, documentPath: string[], fields: PlainData): Promise<UpdateDocumentResponse>

Sets the contents of a document.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.