gcputil

Shared Dart utilities for services running on Google Cloud.

Current helpers cover:

• Google Cloud project and runtime service account metadata.
• Secret Manager lookup with environment-variable fallback.
• Cloud KMS encryption/decryption.
• Google APIs service-account clients backed by Secret Manager keys.
• Enqueuing Cloud Tasks requests that invoke Cloud Run jobs.

Usage

import 'package:gcputil/gcputil.dart';

Future<void> main() async {
  final project = await projectId;
  final apiKey = await secret('my-api-key');

  final key = EncryptionKey(
    name: 'token-key',
    ring: 'application',
    region: 'us-central1',
  );

  final cipher = await encrypt(apiKey, key);
  final plaintext = await decrypt(cipher!, key);

  print('Project: $project');
  print('Recovered secret: $plaintext');
}

The helpers that use Google Cloud metadata credentials are intended for workloads running on Google Cloud, such as Cloud Run, Compute Engine, and environments with Application Default Credentials.

Firebase App Check

Import package:gcputil/app_check.dart (also exported by gcputil.dart) for framework-independent verification. Dart Frog middleware is provided by cloud_frog; gcputil has no Dart Frog dependency.

import 'package:firebase_admin_sdk/firebase_admin_sdk.dart';
import 'package:gcputil/app_check.dart';

final firebase = FirebaseApp.initializeApp(
  name: 'app-check-verification',
  options: AppOptions(projectId: '123456789'),
);
final verifier = AppCheckVerifier.firebase(
  appCheck: firebase.appCheck(),
  projectNumber: '123456789',
  allowedAppIds: {'1:123456789:web:your-app-id'},
);

Future<bool> isAllowed(String? token) async {
  final result = await verifier.verify(token);
  return result.isValid;
}

Use the numeric Google Cloud project number. With firebase_admin_sdk 0.5.x, configure a separate verification-only Firebase app using that number as projectId, so the SDK validates the projects/<number> audience. Keep initialization, disposal, and other Firebase clients owned by your application. Signature verification is delegated to the Firebase Admin SDK; gcputil also checks the exact issuer, audience, subject, expiration, and issuance time.

Omit allowedAppIds to accept any app in the project, or supply a nonempty set of permitted Firebase app IDs. Web, Android, and iOS apps are supported. Tokens longer than maxTokenLength (default 16 KiB) are rejected before verification. For custom adapters and tests, AppCheckVerifier accepts a verifyToken callback which must verify the cryptographic signature, and an optional clock. It is not safe to inject a callback that only decodes JWT claims.

Results expose status (valid, missing, invalid, or unavailable) and an appId for valid tokens. They never include tokens or exception details. SDK invalid-argument and expired-token errors, malformed decoded claims, and failed claim checks count as invalid; other verifier exceptions count as unavailable. Failures already classified as invalid by the SDK cannot be distinguished further by gcputil. Your HTTP layer decides how to respond.

App Check complements user authentication and authorization. Standard verification does not consume tokens or provide replay protection.

See example/app_check_example.dart for a framework-independent integration. Verification follows the Firebase custom backend guidance.