@pyric/cli 0.1.0-alpha.26 → 0.1.0-alpha.28

package/src/verify/staging/rest.ts

@@ -0,0 +1,129 @@
+/**
+ * A minimal Realtime Database REST client for the staging engine: data reads
+ * and writes as admin or as an application user (`auth_variable_override`),
+ * and the rules endpoint (`/.settings/rules.json`).
+ *
+ * Production applies an `auth_variable_override` object as the rules `auth`
+ * variable, `auth.token` claims included; the identity capture recorded in
+ * `packages/conformance/observations/rtdb-staging/rtdb-staging-auth-override.json`
+ * pins that for every field the engine passes.
+ */
+
+/** The rules `auth` variable a request runs as; `null` is signed out. Absent is admin. */
+export type RtdbAuthOverride = Record<string, unknown> | null;
+
+export interface RtdbRestResponse {
+  status: number;
+  /** Parsed JSON body, or the raw text when it is not JSON. */
+  body: unknown;
+  text: string;
+  /** The `ETag` of the location, when the request asked for it (`etag: true`). */
+  etag?: string;
+}
+
+export interface RtdbRestRequest {
+  /** Run as this `auth`; absent runs as admin. */
+  auth?: RtdbAuthOverride;
+  /** REST query parameters (`orderBy`, `startAt`, ...), already JSON-encoded where REST requires it. */
+  query?: Record<string, string>;
+  /** `export` returns priorities as `.priority` keys. */
+  format?: 'export';
+  shallow?: boolean;
+  /** Ask for the location's `ETag` (a read), for a later conditional write. */
+  etag?: boolean;
+  /** Write only if the location's `ETag` is still this one; production answers 412 otherwise. */
+  ifMatch?: string;
+}
+
+export type FetchLike = (url: string, init: { method: string; headers: Record<string, string>; body?: string }) => Promise<{
+  status: number;
+  text(): Promise<string>;
+  headers?: { get(name: string): string | null };
+}>;
+
+export class RtdbRestClient {
+  readonly databaseUrl: string;
+
+  constructor(
+    databaseUrl: string,
+    private readonly token: () => Promise<string>,
+    private readonly fetchImpl: FetchLike = (url, init) => fetch(url, init),
+  ) {
+    this.databaseUrl = databaseUrl.replace(/\/+$/, '');
+  }
+
+  get(path: string, request: RtdbRestRequest = {}): Promise<RtdbRestResponse> {
+    return this.send('GET', path, undefined, request);
+  }
+
+  put(path: string, value: unknown, request: RtdbRestRequest = {}): Promise<RtdbRestResponse> {
+    return this.send('PUT', path, JSON.stringify(value), request);
+  }
+
+  patch(path: string, value: unknown, request: RtdbRestRequest = {}): Promise<RtdbRestResponse> {
+    return this.send('PATCH', path, JSON.stringify(value), request);
+  }
+
+  delete(path: string, request: RtdbRestRequest = {}): Promise<RtdbRestResponse> {
+    return this.send('DELETE', path, undefined, request);
+  }
+
+  /** The deployed rules as stored, comments included. */
+  async getRulesText(): Promise<string> {
+    const res = await this.rules('GET');
+    if (res.status !== 200) throw new Error(`reading the rules of ${this.databaseUrl} failed: HTTP ${res.status} ${res.text.slice(0, 200)}`);
+    return res.text;
+  }
+
+  /** Deploy `source` as the rules, or validate it without deploying (`dryRun`). */
+  putRules(source: string, options: { dryRun?: boolean } = {}): Promise<RtdbRestResponse> {
+    return this.rules('PUT', source, options.dryRun === true);
+  }
+
+  private async rules(method: 'GET' | 'PUT', body?: string, dryRun = false): Promise<RtdbRestResponse> {
+    const url = `${this.databaseUrl}/.settings/rules.json${dryRun ? '?dryRun=true' : ''}`;
+    return this.fetchResponse(url, method, body);
+  }
+
+  private async send(method: string, path: string, body: string | undefined, request: RtdbRestRequest): Promise<RtdbRestResponse> {
+    const params = new URLSearchParams();
+    if (request.auth !== undefined) params.set('auth_variable_override', JSON.stringify(request.auth));
+    if (request.format) params.set('format', request.format);
+    if (request.shallow) params.set('shallow', 'true');
+    for (const [key, value] of Object.entries(request.query ?? {})) params.set(key, value);
+    const query = params.toString();
+    const url = `${this.databaseUrl}${restPath(path) || '/'}.json${query ? `?${query}` : ''}`;
+    const headers: Record<string, string> = {};
+    if (request.etag) headers['X-Firebase-ETag'] = 'true';
+    if (request.ifMatch !== undefined) headers['if-match'] = request.ifMatch;
+    return this.fetchResponse(url, method, body, headers);
+  }
+
+  private async fetchResponse(url: string, method: string, body?: string, extra: Record<string, string> = {}): Promise<RtdbRestResponse> {
+    const res = await this.fetchImpl(url, {
+      method,
+      headers: { Authorization: `Bearer ${await this.token()}`, 'Content-Type': 'application/json', ...extra },
+      ...(body === undefined ? {} : { body }),
+    });
+    const text = await res.text();
+    let parsed: unknown = text;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      // Not JSON: keep the text.
+    }
+    const etag = res.headers?.get('etag') ?? undefined;
+    return { status: res.status, body: parsed, text, ...(etag ? { etag } : {}) };
+  }
+}
+
+/** `/a/b` for any of `a/b`, `/a/b/`, `a//b`; the root is the empty string. */
+export function restPath(path: string): string {
+  const segments = path.split('/').filter(Boolean).map(encodeURIComponent);
+  return segments.length === 0 ? '' : `/${segments.join('/')}`;
+}
+
+/** Whether a REST status is the rules denying the request. */
+export function isRestDenial(status: number): boolean {
+  return status === 401 || status === 403;
+}

package/src/verify/staging/target.ts

@@ -0,0 +1,137 @@
+/**
+ * The staging target `pyric verify --engine staging` replays against, from
+ * the project's `pyric.json`:
+ *
+ *   { "verify": { "staging": { "project": "my-staging", "rtdb": "https://my-verify.firebaseio.com" } } }
+ *
+ * `rtdb` is a database URL or an instance name (`my-verify` resolves to
+ * `https://my-verify.firebaseio.com`; an instance outside us-central1 needs
+ * its full URL). The user brings the instance; pyric provisions nothing.
+ *
+ * An instance the app's own `firebase.json` deploys rules to, or the app
+ * project's default instance, is refused: those hold the app's data.
+ */
+import { readFileSync } from 'node:fs';
+
+import { resolveDatabaseInstance } from 'pyric/sandbox/internal';
+
+import { firebaseToolsConfigstorePath } from '../../cli/firebase-project.js';
+import type { FirebaseJson } from '../../cli/firebase-json.js';
+import { resolveScope, SERVICE_ACCOUNT_BASE64_ENV_KEY, SERVICE_ACCOUNT_FILE_ENV_KEY } from '../../credentials/node/scope.js';
+
+export interface StagingTarget {
+  projectId: string;
+  databaseUrl: string;
+  /** The instance name the URL names. */
+  instance: string;
+}
+
+export class StagingConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'StagingConfigError';
+  }
+}
+
+const CONFIG_EXAMPLE = '{ "verify": { "staging": { "project": "<staging project id>", "rtdb": "https://<dedicated instance>.firebaseio.com" } } }';
+
+/** The staging target in a parsed `pyric.json`, or a config error naming what is missing. */
+export function stagingTargetFrom(config: unknown): StagingTarget {
+  const staging = (config as { verify?: { staging?: unknown } } | null)?.verify?.staging;
+  if (staging === undefined) {
+    throw new StagingConfigError(`no staging target. Add one to pyric.json: ${CONFIG_EXAMPLE}`);
+  }
+  const { project, rtdb } = (staging ?? {}) as { project?: unknown; rtdb?: unknown };
+  if (typeof project !== 'string' || project.trim() === '') {
+    throw new StagingConfigError(`pyric.json verify.staging.project must name the staging project: ${CONFIG_EXAMPLE}`);
+  }
+  if (typeof rtdb !== 'string' || rtdb.trim() === '') {
+    throw new StagingConfigError(`pyric.json verify.staging.rtdb must name the dedicated instance: ${CONFIG_EXAMPLE}`);
+  }
+  const trimmed = rtdb.trim();
+  const databaseUrl = /^[a-z0-9-]+$/i.test(trimmed) ? `https://${trimmed}.firebaseio.com` : trimmed.replace(/\/+$/, '');
+  let instance: string | undefined;
+  try {
+    instance = resolveDatabaseInstance(databaseUrl)?.name;
+  } catch {
+    instance = undefined;
+  }
+  if (instance === undefined) {
+    throw new StagingConfigError(`pyric.json verify.staging.rtdb "${rtdb}" is not a Realtime Database URL or instance name.`);
+  }
+  return { projectId: project.trim(), databaseUrl, instance };
+}
+
+/**
+ * Refuse a staging instance the app uses: one `firebase.json` deploys rules
+ * to (by instance or by a `.firebaserc` target), or the default instance of
+ * the app's project.
+ */
+export function assertNotAppInstance(
+  target: StagingTarget,
+  app: { firebaseJson: FirebaseJson | null; appProjectId?: string; targetInstances?: string[] },
+): void {
+  const declared = new Set<string>(app.targetInstances ?? []);
+  const database = app.firebaseJson?.database as unknown;
+  const entries = Array.isArray(database) ? database : database ? [database] : [];
+  for (const entry of entries) {
+    const instance = (entry as { instance?: unknown }).instance;
+    if (typeof instance === 'string') declared.add(instance);
+  }
+  if (app.appProjectId) declared.add(`${app.appProjectId}-default-rtdb`);
+  if (declared.has(target.instance)) {
+    throw new StagingConfigError(
+      `refusing staging instance ${target.instance}: the app uses it (firebase.json deploys rules to it, or it is the default instance of project ${app.appProjectId}). The staging engine replaces an instance's rules and data, so it needs one dedicated to it.`,
+    );
+  }
+}
+
+/**
+ * An OAuth token for the staging project: a service account or Application
+ * Default Credentials (`resolveScope`), else the Firebase CLI's login
+ * (`firebase login`) while its access token is fresh.
+ */
+export async function stagingToken(
+  projectId: string,
+  deps: { resolve?: typeof resolveScope; env?: NodeJS.ProcessEnv; now?: () => number } = {},
+): Promise<{ token: () => Promise<string>; source: string }> {
+  const env = deps.env ?? process.env;
+  try {
+    const { scope, source } = await (deps.resolve ?? resolveScope)({ projectId, ...(deps.env ? { env: deps.env } : {}) });
+    return { token: () => scope.resolveToken(), source };
+  } catch (resolveError) {
+    // A configured credential that fails is an error to fix, not a reason to
+    // run as the developer's own CLI login instead.
+    if (configuredCredential(env)) throw resolveError;
+    const cli = firebaseCliToken(env, (deps.now ?? Date.now)());
+    if (cli !== undefined) return { token: async () => cli, source: 'firebase login' };
+    throw new StagingConfigError(
+      `no credentials for staging project ${projectId}. ${resolveError instanceof Error ? resolveError.message : String(resolveError)} ` +
+        'Or sign in with `firebase login`: its token is used while it has at least 15 minutes left (run any firebase command to refresh it).',
+    );
+  }
+}
+
+/** Whether the environment names a service account (`resolveScope`'s first two sources). */
+function configuredCredential(env: NodeJS.ProcessEnv): boolean {
+  return [SERVICE_ACCOUNT_BASE64_ENV_KEY, SERVICE_ACCOUNT_FILE_ENV_KEY].some((key) => (env[key] ?? '').trim() !== '');
+}
+
+/** How long a CLI token must stay valid for a run to start with it; it cannot be refreshed mid-run. */
+export const CLI_TOKEN_MARGIN_MS = 15 * 60_000;
+
+/** The Firebase CLI's access token, when its configstore holds one with a known expiry at least the margin away. */
+function firebaseCliToken(env: NodeJS.ProcessEnv, now: number): string | undefined {
+  try {
+    const store = JSON.parse(readFileSync(firebaseToolsConfigstorePath(env), 'utf8')) as {
+      tokens?: { access_token?: unknown; expires_at?: unknown };
+    };
+    const token = store.tokens?.access_token;
+    const expiresAt = store.tokens?.expires_at;
+    if (typeof token !== 'string' || token === '') return undefined;
+    if (typeof expiresAt !== 'number' || expiresAt - now < CLI_TOKEN_MARGIN_MS) return undefined;
+    return token;
+  } catch {
+    return undefined;
+  }
+}