Navigate

API reference

@pyric/cli/verify

46 published symbols from @pyric/cli

Generated from the TypeScript declarations shipped at this import path.

Classes

VerifyInputError

Extends

  • Error

Constructors

Constructor
new VerifyInputError(message: string): VerifyInputError;
Parameters
ParameterType
messagestring
Returns

VerifyInputError

Overrides
Error.constructor

Interfaces

BuildVerifyFixtureInput

Properties

PropertyTypeDescription
authState?{ currentUser?: unknown; users?: unknown[]; }-
authState.currentUser?unknown-
authState.users?unknown[]-
capturedBy?stringStamped into the fixture as capturedBy (identity for boot-time event hydration). Omit for pyric verify builds — they have no instance.
createdAt?string-
description?string-
firestoreRules?string-
observedCalls?Record<string, VerifyObservedCallValues>The values live calls carried, by event id; only those of events in the history are kept.
rtdbDatabaseUrl?string-
rtdbInstances?Record<string, VerifyRtdbInstanceCapture>Every named RTDB instance, by name; see captureRtdbInstances.
rtdbRules?{ rules: Record<string, unknown>; }-
rtdbRules.rulesRecord<string, unknown>-
rtdbState?unknown-
sandboxPick<Sandbox, "snapshot" | "history"> & { currentUser?: unknown; }-
storageRules?stringCurrently-deployed storage rules text. RULES ONLY — there is no storageState input; captured storage OBJECTS are a separate, larger redesign left untouched by this fixture.

DerivedRulesTestCase

Properties

PropertyType
eventIdstring
testCase{ auth?: { tenant?: string; token?: Record<string, unknown>; uid: string; }; data?: Record<string, unknown>; description: string; expectation: "ALLOW" | "DENY"; functionMocks?: { function: "get" | "exists"; path: string; result: boolean | Record<string, unknown>; }[]; method: "delete" | "get" | "list" | "create" | "update"; path: string; query?: { limit?: number; offset?: number; orderBy?: string | Record<string, "ASC" | "DESC">; where?: { field: string; op: string; value: string | number | boolean | (string | number | boolean)[]; }[]; }; requestTime?: string; resource?: Record<string, unknown>; writeMode?: | { kind: "create"; } | { kind: "set"; merge: boolean; } | { kind: "update"; } | { kind: "delete"; }; }
testCase.auth?{ tenant?: string; token?: Record<string, unknown>; uid: string; }
testCase.auth.tenant?string
testCase.auth.token?Record<string, unknown>
testCase.auth.uidstring
testCase.data?Record<string, unknown>
testCase.descriptionstring
testCase.expectation"ALLOW" | "DENY"
testCase.functionMocks?{ function: "get" | "exists"; path: string; result: boolean | Record<string, unknown>; }[]
testCase.method"delete" | "get" | "list" | "create" | "update"
testCase.pathstring
testCase.query?{ limit?: number; offset?: number; orderBy?: string | Record<string, "ASC" | "DESC">; where?: { field: string; op: string; value: string | number | boolean | (string | number | boolean)[]; }[]; }
testCase.query.limit?number
testCase.query.offset?number
testCase.query.orderBy?string | Record<string, "ASC" | "DESC">
testCase.query.where?{ field: string; op: string; value: string | number | boolean | (string | number | boolean)[]; }[]
testCase.requestTime?string
testCase.resource?Record<string, unknown>
testCase.writeMode?| { kind: "create"; } | { kind: "set"; merge: boolean; } | { kind: "update"; } | { kind: "delete"; }

DeriveRulesTestCasesOptions

Properties

PropertyType
includeAllowed?boolean
includeDenied?boolean
includeListenerReads?boolean
mockReads?"strict" | "omit"
service?"firestore"

DeriveRulesTestCasesResult

Properties

PropertyModifierType
cases?readonly{ auth?: { tenant?: string; token?: Record<string, unknown>; uid: string; }; data?: Record<string, unknown>; description: string; expectation: "ALLOW" | "DENY"; functionMocks?: { function: "get" | "exists"; path: string; result: boolean | Record<string, unknown>; }[]; method: "delete" | "get" | "list" | "create" | "update"; path: string; query?: { limit?: number; offset?: number; orderBy?: string | Record<string, "ASC" | "DESC">; where?: { field: string; op: string; value: string | number | boolean | (string | number | boolean)[]; }[]; }; requestTime?: string; resource?: Record<string, unknown>; writeMode?: | { kind: "create"; } | { kind: "set"; merge: boolean; } | { kind: "update"; } | { kind: "delete"; }; }[]
derivedpublicDerivedRulesTestCase[]
okpublicboolean
servicepublic"firestore"
testCasespublic{ auth?: { tenant?: string; token?: Record<string, unknown>; uid: string; }; data?: Record<string, unknown>; description: string; expectation: "ALLOW" | "DENY"; functionMocks?: { function: "get" | "exists"; path: string; result: boolean | Record<string, unknown>; }[]; method: "delete" | "get" | "list" | "create" | "update"; path: string; query?: { limit?: number; offset?: number; orderBy?: string | Record<string, "ASC" | "DESC">; where?: { field: string; op: string; value: string | number | boolean | (string | number | boolean)[]; }[]; }; requestTime?: string; resource?: Record<string, unknown>; writeMode?: | { kind: "create"; } | { kind: "set"; merge: boolean; } | { kind: "update"; } | { kind: "delete"; }; }[]
unsupportedEventspublicVerifyUnsupportedEvent[]
warningspublicVerifyFixtureWarning[]

HostedRulesCredentials

The credentials a hosted run will use, and which source supplied them.

Properties

PropertyType
scopeProjectScope
sourcestring

HostedRulesScope

Which project a hosted run asks about, and which environment it reads.

Properties

PropertyType
env?ProcessEnv
projectId?string

MissingCredentials

No credentials were found, with the sources that were checked for one.

Properties

PropertyType
missingstring
sourcesreadonly string[]

PyricVerifyFixture

Properties

PropertyTypeDescription
capturedBy?stringOpaque id of the sandbox instance that produced this capture (the served SharedWorker’s instanceId). Purely additive: pyric verify ignores it. Present only on captures written by the worker’s capture flush; used by boot-time event hydration to SKIP priming a capture that belongs to a DIFFERENT instance (e.g. another browser profile sharing one pyric sandbox), so someone else’s session never shows up as yours. Absent on older / standalone captures → hydration primes best-effort.
createdAt?string-
description?string-
eventsSandboxEvent[]-
observedCalls?Record<string, VerifyObservedCallValues>The values each live call carried, by its event’s id. A live call’s event holds production’s answer and the local verdict; pyric verify replays it with these against the candidate rules. Absent when the session observed no call that carried any.
schema"pyric.verify.fixture.v1"-
services{ [service: string]: unknown; auth?: { state: { currentUser?: unknown; users?: unknown[]; }; }; firestore?: { rules: VerifyFirestoreRulesBlock; state: { documents: Record<string, Record<string, unknown>>; }; }; rtdb?: { databaseUrl?: string; instances?: Record<string, VerifyRtdbInstanceCapture>; rules: VerifyRtdbRulesBlock; state: { tree: unknown; }; }; storage?: { rules: VerifyStorageRulesBlock; state: unknown; }; }-
services.auth?{ state: { currentUser?: unknown; users?: unknown[]; }; }-
services.auth.state{ currentUser?: unknown; users?: unknown[]; }-
services.auth.state.currentUser?unknown-
services.auth.state.users?unknown[]-
services.firestore?{ rules: VerifyFirestoreRulesBlock; state: { documents: Record<string, Record<string, unknown>>; }; }-
services.firestore.rulesVerifyFirestoreRulesBlock-
services.firestore.state{ documents: Record<string, Record<string, unknown>>; }-
services.firestore.state.documentsRecord<string, Record<string, unknown>>-
services.rtdb?{ databaseUrl?: string; instances?: Record<string, VerifyRtdbInstanceCapture>; rules: VerifyRtdbRulesBlock; state: { tree: unknown; }; }-
services.rtdb.databaseUrl?stringThe default instance’s URL, when the session knew its name. pyric verify reads the name from it, so rules firebase.json deploys to that name check the default instance.
services.rtdb.instances?Record<string, VerifyRtdbInstanceCapture>Every named instance the session held, by instance name. The events of a named instance carry its name in instance. Absent on captures recorded before instances were captured.
services.rtdb.rulesVerifyRtdbRulesBlockThe default instance’s rules and data.
services.rtdb.state{ tree: unknown; }-
services.rtdb.state.treeunknown-
services.storage?{ rules: VerifyStorageRulesBlock; state: unknown; }-
services.storage.rulesVerifyStorageRulesBlockRULES TEXT ONLY — captured object state is a separate, larger redesign (persistence.ts’s IDB blob store) and is deliberately left untouched here. state stays null until that lands.
services.storage.stateunknown-
storageDeniedWrites?Record<string, RecordedStorageDeniedWrite>Redacted request.resource and existing resource bindings for denied Storage operations, keyed by operation event id so SandboxOperationEvent stays narrow on the Traffic chip and Studio event stream.

VerifyEngineResult

Properties

PropertyType
checkedEventsnumber
derivation?DeriveRulesTestCasesResult
divergencesVerifyDivergence[]
engineVerifyEngine
failed?number
notes?string[]
okboolean
passed?number
results?TestResult[]
testCases?number
unevaluatedEvents?VerifyUnevaluatedEvent[]
unsupported?number

VerifyFirestoreRulesBlock

Properties

PropertyType
format"firestore.rules"
sourcestring

VerifyFixtureOptions

Properties

PropertyTypeDescription
caseDerivation?Omit<DeriveRulesTestCasesOptions, "service">-
engines?VerifyEngine[]-
rulesVerifyRulesInput-
rulesTestApi?{ expressionReportLevel?: ExpressionReportLevel; scope: ProjectScope; }-
rulesTestApi.expressionReportLevel?ExpressionReportLevel-
rulesTestApi.scopeProjectScope-
services?VerifiableService[]-
staging?{ client: RtdbRestClient; projectId: string; } & StagingRunHooksThe staging engine’s instance: a client for a dedicated RTDB instance enrolled with pyric verify staging init, and the project it is enrolled for. Required when engines includes staging.

VerifyObservedCallValues

What one live call carried for the local rules, kept beside its event rather than on it: the token’s claim values, the data a Firestore write sent, and the document a Firestore read returned.

Properties

PropertyType
claims?Record<string, unknown>
document?Record<string, unknown>
writeData?ObservedWriteValue

VerifyResult

Properties

PropertyType
okboolean
servicesPartial<Record<VerifiableService, VerifyServiceResult>>

VerifyRtdbInstanceCapture

One named RTDB instance in a capture: its active rules and its data.

Properties

PropertyType
rulesVerifyRtdbRulesBlock
state{ tree: unknown; }
state.treeunknown

VerifyRtdbRulesBlock

Properties

PropertyType
format"rtdb.rules.json"
json{ rules: Record<string, unknown>; }
json.rulesRecord<string, unknown>

VerifyServiceResult

Properties

PropertyTypeDescription
checkedEventsnumber-
divergencesVerifyDivergence[]-
engines?Partial<Record<VerifyEngine, VerifyEngineResult>>-
notes?string[]Informational notes describing skipped or unevaluated events that did not produce divergences.
okboolean-
serviceVerifiableService-
skippedInstances?string[]RTDB: the named instances the session used that no candidate rules were passed for, so they were not checked.
unevaluatedEvents?VerifyUnevaluatedEvent[]Events skipped because captured bindings were redacted and candidate rules read those fields.

VerifyStorageRulesBlock

Properties

PropertyType
format"storage.rules"
sourcestring

VerifyToolDeps

Properties

PropertyType
scope?ProjectScope

VerifyUnevaluatedEvent

Properties

PropertyType
bucket?string
eventIdstring
method?string
needsstring[]
path?string
reasonstring

Type Aliases

HostedRulesTester()

type HostedRulesTester = (scope: ProjectScope, rules: string, cases: TestCase[], options?: {
  expressionReportLevel?: ExpressionReportLevel;
}) => Promise<TestFirestoreRulesResult>;

What one hosted run needs beyond the cases: a project and a token for it.

Parameters

ParameterType
scopeProjectScope
rulesstring
casesTestCase[]
options?{ expressionReportLevel?: ExpressionReportLevel; }
options.expressionReportLevel?ExpressionReportLevel

Returns

Promise<TestFirestoreRulesResult>


HostedRulesTestOutcome

type HostedRulesTestOutcome =
  | {
  credentials: HostedRulesCredentials;
  result: TestFirestoreRulesResult;
}
  | MissingCredentials;

What a run that had to find its own credentials came back with.


VerifiableService

type VerifiableService = "firestore" | "rtdb" | "storage";

VerifyDivergence

type VerifyDivergence = VerifyDivergenceKind & {
  bucket?: string;
  instance?: string;
};

A divergence; an RTDB divergence on a named instance names it in instance, and a Storage divergence names its bucket in bucket.

Type Declaration

bucket?
optional bucket: string;
instance?
optional instance: string;

VerifyEngine

type VerifyEngine = "sandbox" | "rulesTestApi" | "staging";

VerifyFixtureWarning

type VerifyFixtureWarning = {
  code: string;
  eventId?: string;
  message: string;
  method?: string;
  path?: string;
  service: "firestore";
};

Properties

PropertyType
codestring
eventId?string
messagestring
method?string
path?string
service"firestore"

VerifyRulesInput

type VerifyRulesInput = {
  firestore?:   | string
     | {
     source: string;
   };
  rtdb?: RtdbCandidateRules;
  rtdbInstances?: Record<string, RtdbCandidateRules>;
  storage?: StorageCandidateSource;
  storageBuckets?: Record<string, StorageCandidateSource>;
};

Properties

PropertyTypeDescription
firestore?| string | { source: string; }-
rtdb?RtdbCandidateRulesThe default RTDB instance’s candidate rules.
rtdbInstances?Record<string, RtdbCandidateRules>Each named RTDB instance’s candidate rules, by the instance name its events carry. A recorded instance without an entry is not checked, and the result names it in skippedInstances.
storage?StorageCandidateSourceThe default bucket’s candidate Storage rules, or every bucket’s when storageBuckets is absent.
storageBuckets?Record<string, StorageCandidateSource>Each bucket’s candidate Storage rules, by the bucket name its rules see. Passing it replays each bucket under its own rules; a recorded bucket without an entry, other than the default bucket, replays as locked.

VerifyUnsupportedEvent

type VerifyUnsupportedEvent = {
  eventId?: string;
  method?: string;
  path?: string;
  reason: string;
  service: "firestore";
};

Properties

PropertyType
eventId?string
method?string
path?string
reasonstring
service"firestore"

Variables

HOSTED_CREDENTIAL_ENV_KEYS

const HOSTED_CREDENTIAL_ENV_KEYS: readonly string[];

The sources credential discovery reads, in the order it reads them.


HOSTED_CREDENTIAL_SOURCES

const HOSTED_CREDENTIAL_SOURCES: "FIREBASE_SA_BASE64, GOOGLE_APPLICATION_CREDENTIALS, or Application Default Credentials from `gcloud auth application-default login` with a project id in PYRIC_PROJECT" = "FIREBASE_SA_BASE64, GOOGLE_APPLICATION_CREDENTIALS, or Application Default Credentials from gcloud auth application-default login with a project id in PYRIC_PROJECT";

The credential sources the hosted engine reads, in the order it reads them.


VERIFY_FIXTURE_SCHEMA

const VERIFY_FIXTURE_SCHEMA: "pyric.verify.fixture.v1";

Functions

buildVerifyFixture()

function buildVerifyFixture(input: BuildVerifyFixtureInput): PyricVerifyFixture;

Parameters

ParameterType
inputBuildVerifyFixtureInput

Returns

PyricVerifyFixture


capturedDefaultRtdbInstance()

function capturedDefaultRtdbInstance(fixture: PyricVerifyFixture): string;

The default instance’s name, when the capture recorded its URL.

Parameters

ParameterType
fixturePyricVerifyFixture

Returns

string


createVerifyTools()

function createVerifyTools(deps?: VerifyToolDeps): ToolHandler<unknown, unknown>[];

Parameters

ParameterType
deps?VerifyToolDeps

Returns

ToolHandler<unknown, unknown>[]


deriveRulesTestCases()

function deriveRulesTestCases(fixtureInput: unknown, opts?: DeriveRulesTestCasesOptions): DeriveRulesTestCasesResult;

Parameters

ParameterType
fixtureInputunknown
opts?DeriveRulesTestCasesOptions

Returns

DeriveRulesTestCasesResult


executeHostedRulesTest()

function executeHostedRulesTest(
   scope: ProjectScope,
   rules: string,
   cases: {
  auth?: {
     tenant?: string;
     token?: Record<string, unknown>;
     uid: string;
  };
  data?: Record<string, unknown>;
  description: string;
  expectation: "ALLOW" | "DENY";
  functionMocks?: {
     function: "get" | "exists";
     path: string;
     result: boolean | Record<string, unknown>;
  }[];
  method: "delete" | "get" | "list" | "create" | "update";
  path: string;
  query?: {
     limit?: number;
     offset?: number;
     orderBy?: string | Record<string, "ASC" | "DESC">;
     where?: {
        field: string;
        op: string;
        value: string | number | boolean | (string | number | boolean)[];
     }[];
  };
  requestTime?: string;
  resource?: Record<string, unknown>;
  writeMode?:   | {
     kind: "create";
   }
     | {
     kind: "set";
     merge: boolean;
   }
     | {
     kind: "update";
   }
     | {
     kind: "delete";
   };
}[],
   options?: {
  expressionReportLevel?: ExpressionReportLevel;
}): Promise<TestFirestoreRulesResult>;

Run cases on the hosted API against an already-resolved scope. This is the only construction of the client; every path that reaches Google goes through it.

Parameters

ParameterType
scopeProjectScope
rulesstring
cases{ auth?: { tenant?: string; token?: Record<string, unknown>; uid: string; }; data?: Record<string, unknown>; description: string; expectation: "ALLOW" | "DENY"; functionMocks?: { function: "get" | "exists"; path: string; result: boolean | Record<string, unknown>; }[]; method: "delete" | "get" | "list" | "create" | "update"; path: string; query?: { limit?: number; offset?: number; orderBy?: string | Record<string, "ASC" | "DESC">; where?: { field: string; op: string; value: string | number | boolean | (string | number | boolean)[]; }[]; }; requestTime?: string; resource?: Record<string, unknown>; writeMode?: | { kind: "create"; } | { kind: "set"; merge: boolean; } | { kind: "update"; } | { kind: "delete"; }; }[]
options?{ expressionReportLevel?: ExpressionReportLevel; }
options.expressionReportLevel?ExpressionReportLevel

Returns

Promise<TestFirestoreRulesResult>


fixtureVerifiableServices()

function fixtureVerifiableServices(fixture: PyricVerifyFixture): ("firestore" | "rtdb" | "storage")[];

Parameters

ParameterType
fixturePyricVerifyFixture

Returns

("firestore" | "rtdb" | "storage")[]


hostedRulesCredentials()

function hostedRulesCredentials(scope?: HostedRulesScope): Promise<
  | HostedRulesCredentials
| MissingCredentials>;

The project scope a hosted run would use, or the sentence that says which credentials are missing and how to supply them. Reading is all this does: a source that is absent is reported, never created.

Parameters

ParameterType
scope?HostedRulesScope

Returns

Promise< | HostedRulesCredentials | MissingCredentials>


isMissingCredentials()

function isMissingCredentials<Answered>(outcome: MissingCredentials | Answered): outcome is MissingCredentials;

Whether one outcome is the absence of credentials rather than an answer. Both the discovery call and the full run can come back this way, so the check is written once over either.

Type Parameters

Type Parameter
Answered extends object

Parameters

ParameterType
outcomeMissingCredentials | Answered

Returns

outcome is MissingCredentials


parseVerifyFixture()

function parseVerifyFixture(value: unknown): PyricVerifyFixture;

Parameters

ParameterType
valueunknown

Returns

PyricVerifyFixture


recordedRtdbInstances()

function recordedRtdbInstances(fixture: PyricVerifyFixture): string[];

The named instances a capture recorded: the ones its events name and the ones it captured, sorted.

Parameters

ParameterType
fixturePyricVerifyFixture

Returns

string[]


recordsDefaultRtdbInstance()

function recordsDefaultRtdbInstance(fixture: PyricVerifyFixture): boolean;

Whether a capture recorded the default instance: an event on it, data in it, or no named instance at all, as a capture recorded before instances were captured is the default instance’s alone.

Parameters

ParameterType
fixturePyricVerifyFixture

Returns

boolean


restoreStorageRulesFromFixture()

function restoreStorageRulesFromFixture(fixture: PyricVerifyFixture, sandbox: Sandbox): void;

Re-deploy a fixture’s captured storage rules into a sandbox’s storage evaluator. RULES TEXT ONLY, mirroring the capture-side scope note: this never touches storage OBJECTS (persistence.ts’s IDB blob store) — only fixture.services.storage.rules.source is applied.

Storage rules are honored only on the FIRST getStorageSandbox call per Sandbox (see storage/service.ts), so this must run before any other code opens the storage service on sandbox — exactly the same ordering constraint firestore/rtdb rules already have at restore time. A no-op when the fixture carries no storage block.

Parameters

ParameterType
fixturePyricVerifyFixture
sandboxSandbox

Returns

void


runHostedRulesTest()

function runHostedRulesTest(
   scope: HostedRulesScope,
   rules: string,
   cases: {
  auth?: {
     tenant?: string;
     token?: Record<string, unknown>;
     uid: string;
  };
  data?: Record<string, unknown>;
  description: string;
  expectation: "ALLOW" | "DENY";
  functionMocks?: {
     function: "get" | "exists";
     path: string;
     result: boolean | Record<string, unknown>;
  }[];
  method: "delete" | "get" | "list" | "create" | "update";
  path: string;
  query?: {
     limit?: number;
     offset?: number;
     orderBy?: string | Record<string, "ASC" | "DESC">;
     where?: {
        field: string;
        op: string;
        value: string | number | boolean | (string | number | boolean)[];
     }[];
  };
  requestTime?: string;
  resource?: Record<string, unknown>;
  writeMode?:   | {
     kind: "create";
   }
     | {
     kind: "set";
     merge: boolean;
   }
     | {
     kind: "update";
   }
     | {
     kind: "delete";
   };
}[]): Promise<HostedRulesTestOutcome>;

Find credentials and decide the cases on the hosted API. Credentials are looked for first, so a run without them never builds a client.

Parameters

ParameterType
scopeHostedRulesScope
rulesstring
cases{ auth?: { tenant?: string; token?: Record<string, unknown>; uid: string; }; data?: Record<string, unknown>; description: string; expectation: "ALLOW" | "DENY"; functionMocks?: { function: "get" | "exists"; path: string; result: boolean | Record<string, unknown>; }[]; method: "delete" | "get" | "list" | "create" | "update"; path: string; query?: { limit?: number; offset?: number; orderBy?: string | Record<string, "ASC" | "DESC">; where?: { field: string; op: string; value: string | number | boolean | (string | number | boolean)[]; }[]; }; requestTime?: string; resource?: Record<string, unknown>; writeMode?: | { kind: "create"; } | { kind: "set"; merge: boolean; } | { kind: "update"; } | { kind: "delete"; }; }[]

Returns

Promise<HostedRulesTestOutcome>


useHostedRulesTester()

function useHostedRulesTester(next: () => HostedRulesTester): () => void;

Replace the client builder for one test, and restore it through the returned function.

Parameters

ParameterType
next() => HostedRulesTester

Returns

(): void;
Returns

void


verifyFixture()

function verifyFixture(fixtureInput: unknown, opts: VerifyFixtureOptions): Promise<VerifyResult>;

Parameters

ParameterType
fixtureInputunknown
optsVerifyFixtureOptions

Returns

Promise<VerifyResult>