pyric 0.0.1 → 0.1.0-alpha.8

package/dist/storage/rules.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Storage rules — standalone subset.
+ *
+ * Why a separate evaluator (not the Firestore one):
+ *
+ * Firestore's grammar header is `service cloud.firestore` and its
+ * bindings (`request.method` enum of get/list/create/update/delete,
+ * `resource.data`, etc.) are deeply Firestore-shaped. Storage uses
+ * `service firebase.storage` with different bindings
+ * (`request.resource.size`, `request.resource.contentType`,
+ * `resource.metadata`). The user's call (recorded in the v1 scope
+ * plan): keep them independent so neither battles the other for
+ * grammar generality.
+ *
+ * Subset implemented in Slice 8 (Section 5 of the v1 scope):
+ *
+ *   - `service firebase.storage { match … }` header
+ *   - Nested `match` blocks with path segments:
+ *       literal (`sessions`), parameter (`{sessionId}`), and
+ *       multi-segment wildcard (`{allPaths=**}`)
+ *   - `allow read | write : if <expr>;` (other granular verbs
+ *     defer)
+ *   - Expressions:
+ *       literals: number, string, boolean, null
+ *       identifiers: `request`, `resource`, plus path parameters
+ *       member access (`a.b`), index access (`a['b']`)
+ *       unary: `!`
+ *       binary: `&& || == != < > <= >= + - * /`
+ *       parens
+ *
+ * Out of scope (mirrors the survey + plan): `request.time`,
+ * `matches()`/regex, function definitions, `customMetadata.<field>`
+ * deep access (use bracket form against `resource.metadata` when
+ * really needed), the granular verbs `get | list | create | update
+ * | delete`. Hooks for adding them later live at the obvious
+ * extension seams in the parser + evaluator.
+ */
+/** Method abstraction the operation layer hands to the evaluator. */
+export type StorageMethod = 'read' | 'write';
+/** Identity passed in with the request. `null` is anonymous. */
+export interface StorageAuth {
+    uid: string;
+    token?: Record<string, unknown>;
+}
+/** Inbound request bindings the rules see. */
+export interface StorageRequest {
+    auth: StorageAuth | null;
+    method: StorageMethod;
+    /** Path of the object the request targets. */
+    path: string;
+    /** Per-Firebase: on writes, `request.resource` describes the
+     *  about-to-write object. Omit for reads (the rules language
+     *  treats `request.resource` as unset there). */
+    resource?: {
+        size: number;
+        contentType?: string;
+        metadata?: Record<string, string>;
+    };
+}
+/** Existing-object bindings (for `resource.*`). `null` when no
+ *  object exists yet (creates). */
+export interface StorageResource {
+    size: number;
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+export interface EvaluationInput {
+    request: StorageRequest;
+    resource: StorageResource | null;
+}
+export interface EvaluationResult {
+    allowed: boolean;
+    /** Human-readable explanation of why — used by Slice 8's
+     *  integration to populate `storage/unauthorized` error
+     *  messages. */
+    reasons: string[];
+}
+/** Opaque parsed-rules handle returned by `parseStorageRules`. */
+export interface StorageRules {
+    readonly _root: MatchBlock;
+}
+interface MatchBlock {
+    segments: PathSegment[];
+    children: MatchBlock[];
+    allows: AllowRule[];
+}
+type PathSegment = {
+    kind: 'literal';
+    value: string;
+} | {
+    kind: 'param';
+    name: string;
+} | {
+    kind: 'wildcard';
+    name: string;
+};
+interface AllowRule {
+    verbs: StorageMethod[];
+    condition: Expr | null;
+}
+type BinaryOp = '&&' | '||' | '==' | '!=' | '<' | '>' | '<=' | '>=' | '+' | '-' | '*' | '/';
+type Expr = {
+    kind: 'literal';
+    value: number | string | boolean | null;
+} | {
+    kind: 'ident';
+    name: string;
+} | {
+    kind: 'member';
+    target: Expr;
+    name: string;
+} | {
+    kind: 'index';
+    target: Expr;
+    index: Expr;
+} | {
+    kind: 'unary';
+    op: '!';
+    arg: Expr;
+} | {
+    kind: 'binary';
+    op: BinaryOp;
+    left: Expr;
+    right: Expr;
+};
+/**
+ * Parse a Storage rules source into an opaque handle. Throws
+ * `SyntaxError` on malformed input. Used by Slice 8's
+ * `getStorage(ctx, { rules })` to validate upfront.
+ */
+export declare function parseStorageRules(source: string): StorageRules;
+/**
+ * Adapt a persisted metadata record into the `resource.*` binding the
+ * rules language sees.
+ *
+ * The persistence layer stores client custom metadata under
+ * `customMetadata` (`StoredMetadata.customMetadata`), but the rules
+ * language exposes it as `resource.metadata.<key>`. Without this
+ * mapping every `resource.metadata.X` reference reads `undefined` and
+ * metadata-based authorization fails open (#764). This is the single
+ * seam that keeps the two shapes reconciled — every gated read/delete
+ * call site feeds `resource` through here.
+ */
+export declare function resourceFromStored(stored: {
+    size: number;
+    contentType?: string;
+    customMetadata?: Record<string, string>;
+} | null | undefined): StorageResource | null;
+/**
+ * Build the `request.resource` binding for a write. The custom
+ * metadata the client is about to set becomes `request.resource.metadata`
+ * so `allow write: if request.resource.metadata.owner == request.auth.uid`
+ * evaluates against the real incoming value rather than `undefined`.
+ */
+export declare function requestResourceFor(args: {
+    size: number;
+    contentType?: string;
+    customMetadata?: Record<string, string>;
+}): NonNullable<StorageRequest['resource']>;
+/**
+ * Evaluate the rules against a request + resource binding. Returns
+ * `{ allowed, reasons }`. `allowed` is true iff any `allow` clause
+ * at any matching match block evaluates to a truthy condition.
+ *
+ * Path-matching strategy: the request's path is segmented and
+ * walked against the AST's match tree. Wildcards (`{p=**}`) match
+ * zero or more remaining segments; named params bind one segment.
+ *
+ * Multi-clause failure mode: when no clause matches, `reasons`
+ * contains a short trace ("no match found for path X" or "rule at
+ * match /sessions/{id} denied: condition false"). Helpful for the
+ * playground's error surface.
+ */
+export declare function evaluateStorageRules(rules: StorageRules, input: EvaluationInput): EvaluationResult;
+export {};
+//# sourceMappingURL=rules.d.ts.map

package/dist/storage/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/storage/rules.ts"],"names":[],"mappings":"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"}