Classes
VerifyInputError
Extends
Error
Constructors
Constructor
new VerifyInputError(message: string): VerifyInputError;
Parameters
| Parameter | Type |
|---|---|
message | string |
Returns
Overrides
Error.constructor
Interfaces
BuildVerifyFixtureInput
Properties
| Property | Type | Description |
|---|---|---|
authState? | { currentUser?: unknown; users?: unknown[]; } | - |
authState.currentUser? | unknown | - |
authState.users? | unknown[] | - |
capturedBy? | string | Stamped 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.rules | Record<string, unknown> | - |
rtdbState? | unknown | - |
sandbox | Pick<Sandbox, "snapshot" | "history"> & { currentUser?: unknown; } | - |
storageRules? | string | Currently-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
DeriveRulesTestCasesOptions
Properties
| Property | Type |
|---|---|
includeAllowed? | boolean |
includeDenied? | boolean |
includeListenerReads? | boolean |
mockReads? | "strict" | "omit" |
service? | "firestore" |
DeriveRulesTestCasesResult
Properties
| Property | Modifier | Type |
|---|---|---|
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"; }; }[] |
derived | public | DerivedRulesTestCase[] |
ok | public | boolean |
service | public | "firestore" |
testCases | public | { 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"; }; }[] |
unsupportedEvents | public | VerifyUnsupportedEvent[] |
warnings | public | VerifyFixtureWarning[] |
HostedRulesCredentials
The credentials a hosted run will use, and which source supplied them.
Properties
HostedRulesScope
Which project a hosted run asks about, and which environment it reads.
Properties
MissingCredentials
No credentials were found, with the sources that were checked for one.
Properties
PyricVerifyFixture
Properties
| Property | Type | Description |
|---|---|---|
capturedBy? | string | Opaque 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 | - |
events | SandboxEvent[] | - |
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.rules | VerifyFirestoreRulesBlock | - |
services.firestore.state | { documents: Record<string, Record<string, unknown>>; } | - |
services.firestore.state.documents | Record<string, Record<string, unknown>> | - |
services.rtdb? | { databaseUrl?: string; instances?: Record<string, VerifyRtdbInstanceCapture>; rules: VerifyRtdbRulesBlock; state: { tree: unknown; }; } | - |
services.rtdb.databaseUrl? | string | The 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.rules | VerifyRtdbRulesBlock | The default instance’s rules and data. |
services.rtdb.state | { tree: unknown; } | - |
services.rtdb.state.tree | unknown | - |
services.storage? | { rules: VerifyStorageRulesBlock; state: unknown; } | - |
services.storage.rules | VerifyStorageRulesBlock | RULES 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.state | unknown | - |
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
| Property | Type |
|---|---|
checkedEvents | number |
derivation? | DeriveRulesTestCasesResult |
divergences | VerifyDivergence[] |
engine | VerifyEngine |
failed? | number |
notes? | string[] |
ok | boolean |
passed? | number |
results? | TestResult[] |
testCases? | number |
unevaluatedEvents? | VerifyUnevaluatedEvent[] |
unsupported? | number |
VerifyFirestoreRulesBlock
Properties
VerifyFixtureOptions
Properties
| Property | Type | Description |
|---|---|---|
caseDerivation? | Omit<DeriveRulesTestCasesOptions, "service"> | - |
engines? | VerifyEngine[] | - |
rules | VerifyRulesInput | - |
rulesTestApi? | { expressionReportLevel?: ExpressionReportLevel; scope: ProjectScope; } | - |
rulesTestApi.expressionReportLevel? | ExpressionReportLevel | - |
rulesTestApi.scope | ProjectScope | - |
services? | VerifiableService[] | - |
staging? | { client: RtdbRestClient; projectId: string; } & StagingRunHooks | The 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
| Property | Type |
|---|---|
claims? | Record<string, unknown> |
document? | Record<string, unknown> |
writeData? | ObservedWriteValue |
VerifyResult
Properties
| Property | Type |
|---|---|
ok | boolean |
services | Partial<Record<VerifiableService, VerifyServiceResult>> |
VerifyRtdbInstanceCapture
One named RTDB instance in a capture: its active rules and its data.
Properties
| Property | Type |
|---|---|
rules | VerifyRtdbRulesBlock |
state | { tree: unknown; } |
state.tree | unknown |
VerifyRtdbRulesBlock
Properties
| Property | Type |
|---|---|
format | "rtdb.rules.json" |
json | { rules: Record<string, unknown>; } |
json.rules | Record<string, unknown> |
VerifyServiceResult
Properties
| Property | Type | Description |
|---|---|---|
checkedEvents | number | - |
divergences | VerifyDivergence[] | - |
engines? | Partial<Record<VerifyEngine, VerifyEngineResult>> | - |
notes? | string[] | Informational notes describing skipped or unevaluated events that did not produce divergences. |
ok | boolean | - |
service | VerifiableService | - |
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
VerifyToolDeps
Properties
VerifyUnevaluatedEvent
Properties
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
| Parameter | Type |
|---|---|
scope | ProjectScope |
rules | string |
cases | TestCase[] |
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
VerifyRulesInput
type VerifyRulesInput = {
firestore?: | string
| {
source: string;
};
rtdb?: RtdbCandidateRules;
rtdbInstances?: Record<string, RtdbCandidateRules>;
storage?: StorageCandidateSource;
storageBuckets?: Record<string, StorageCandidateSource>;
};
Properties
VerifyUnsupportedEvent
type VerifyUnsupportedEvent = {
eventId?: string;
method?: string;
path?: string;
reason: string;
service: "firestore";
};
Properties
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
| Parameter | Type |
|---|---|
input | BuildVerifyFixtureInput |
Returns
capturedDefaultRtdbInstance()
function capturedDefaultRtdbInstance(fixture: PyricVerifyFixture): string;
The default instance’s name, when the capture recorded its URL.
Parameters
| Parameter | Type |
|---|---|
fixture | PyricVerifyFixture |
Returns
string
createVerifyTools()
function createVerifyTools(deps?: VerifyToolDeps): ToolHandler<unknown, unknown>[];
Parameters
| Parameter | Type |
|---|---|
deps? | VerifyToolDeps |
Returns
ToolHandler<unknown, unknown>[]
deriveRulesTestCases()
function deriveRulesTestCases(fixtureInput: unknown, opts?: DeriveRulesTestCasesOptions): DeriveRulesTestCasesResult;
Parameters
| Parameter | Type |
|---|---|
fixtureInput | unknown |
opts? | DeriveRulesTestCasesOptions |
Returns
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
| Parameter | Type |
|---|---|
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; } |
options.expressionReportLevel? | ExpressionReportLevel |
Returns
Promise<TestFirestoreRulesResult>
fixtureVerifiableServices()
function fixtureVerifiableServices(fixture: PyricVerifyFixture): ("firestore" | "rtdb" | "storage")[];
Parameters
| Parameter | Type |
|---|---|
fixture | PyricVerifyFixture |
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
| Parameter | Type |
|---|---|
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
| Parameter | Type |
|---|---|
outcome | MissingCredentials | Answered |
Returns
outcome is MissingCredentials
parseVerifyFixture()
function parseVerifyFixture(value: unknown): PyricVerifyFixture;
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
recordedRtdbInstances()
function recordedRtdbInstances(fixture: PyricVerifyFixture): string[];
The named instances a capture recorded: the ones its events name and the ones it captured, sorted.
Parameters
| Parameter | Type |
|---|---|
fixture | PyricVerifyFixture |
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
| Parameter | Type |
|---|---|
fixture | PyricVerifyFixture |
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
| Parameter | Type |
|---|---|
fixture | PyricVerifyFixture |
sandbox | Sandbox |
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
| Parameter | Type |
|---|---|
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"; }; }[] |
Returns
Promise<HostedRulesTestOutcome>
useHostedRulesTester()
function useHostedRulesTester(next: () => HostedRulesTester): () => void;
Replace the client builder for one test, and restore it through the returned function.
Parameters
| Parameter | Type |
|---|---|
next | () => HostedRulesTester |
Returns
(): void;
Returns
void
verifyFixture()
function verifyFixture(fixtureInput: unknown, opts: VerifyFixtureOptions): Promise<VerifyResult>;
Parameters
| Parameter | Type |
|---|---|
fixtureInput | unknown |
opts | VerifyFixtureOptions |
Returns
Promise<VerifyResult>