npm - @pyric/cli - Versions diffs - 0.1.0-alpha.9 - Mend

@pyric/cli 0.1.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1169) hide show

package/dist/serve/docs-ui/docs/pyric-storage-reference-conformance-gaps/index.html ADDED Viewed

@@ -0,0 +1,137 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Storage rules gaps: where pyric and Firebase disagree · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/" aria-current="true"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/" aria-current="true"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-storage/">pyric / storage</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Storage rules gaps</span> </li> </ol> </nav>  <article class="prose">  <h1 id="storage-rules-gaps-where-pyric-and-firebase-disagree">Storage rules gaps: where pyric and Firebase disagree</h1>
+<p>A gap is a rule that gets one answer from pyric and a different answer from
+Firebase. You write the rule once. pyric allows the request and Firebase
+denies it, or the other way round. The rule you tested is not the rule you
+shipped.</p>
+<p>Every gap on this page was captured from the production Rules Test API, not
+inferred. There is one gap in the storage evaluator today. It affects the
+create-if-absent idiom, which is common. Read that one section and you are
+done.</p>
+<h2 id="how-to-read-severity">How to read severity</h2>
+<p>Every gap has two facts. A single label hides one of them, so this page
+reports both.</p>
+<p><strong>Fidelity</strong> is the direction of the disagreement. Either pyric allows where
+Firebase denies, or pyric denies where Firebase allows. Either way the verdict
+you get locally is not the verdict you get in production, and the whole point
+of a local mirror is that the two match.</p>
+<p><strong>Production impact</strong> is whether the gap lets a request through in production
+that should not get through. It follows from the direction.</p>
+<ul>
+<li><strong>pyric allows, Firebase denies.</strong> Production is stricter than pyric. Nothing
+pyric wrongly allowed reaches production, so there is no production hole. The
+cost is trust: a local ALLOW you relied on is wrong, and a legitimate
+operation you validated locally can be refused in production.</li>
+<li><strong>pyric denies, Firebase allows.</strong> Production is more permissive than pyric.
+A request your local mirror refused can succeed in production. This is the
+direction that ships a hole: a rule you tested as blocking may not block.</li>
+</ul>
+<p>Read both. A broken verdict with no production hole is still a broken verdict,
+and a narrow trigger in the permissive direction is still the direction that
+leaks.</p>
+<h2 id="resource--null-allows-a-create-in-pyric-that-firebase-denies"><code>resource == null</code> allows a create in pyric that Firebase denies</h2>
+<p><strong>Fidelity:</strong> pyric allows, Firebase denies.
+<strong>Production impact:</strong> no attacker reaches production, because Firebase denies
+this create too. But the companion cases match on both sides (an update, and a
+create over an object that already exists), so a real ruleset that guards writes
+with <code>resource == null</code> / <code>resource != null</code> still denies unauthorized writes in
+production. Only the case the guard exists for, the genuinely new object,
+differs: locally it uploads, in production it is refused.</p>
+<h3 id="what-you-would-write">What you would write</h3>
+<p>The create-if-absent guard. Anyone may upload a new object, nobody may
+overwrite one:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>rules_version = '2';</span></span>
+<span class="line"><span>service firebase.storage {</span></span>
+<span class="line"><span>  match /b/{bucket}/o {</span></span>
+<span class="line"><span>    match /uploads/{fileId} {</span></span>
+<span class="line"><span>      allow create: if resource == null;</span></span>
+<span class="line"><span>      allow update: if resource != null;</span></span>
+<span class="line"><span>    }</span></span>
+<span class="line"><span>  }</span></span>
+<span class="line"><span>}</span></span></code></pre>
+<h3 id="what-happens">What happens</h3>
+<p>Upload to <code>uploads/report.pdf</code> when no such object exists yet:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">getStorage</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">ref</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">uploadBytes</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/storage'</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> uploadBytes</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">ref</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">getStorage</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">app</span><span style="color:#ABB2BF">), </span><span style="color:#98C379">'uploads/report.pdf'</span><span style="color:#ABB2BF">), </span><span style="color:#E06C75">bytes</span><span style="color:#ABB2BF">);</span></span></code></pre>
+<p>In pyric the create is ALLOWED. <code>resource</code> is null before the object exists,
+so <code>resource == null</code> is true and the rule passes.</p>
+<p>In Firebase the create is DENIED. Firebase never evaluates the comparison.
+Reading <code>resource</code> on a create where no object exists raises a null value
+error, the expression errors, and an errored expression denies.</p>
+<p>Your rule does not do what you think it does. Locally every first upload
+succeeds. In production every first upload is refused, and a <code>create</code> rule
+guarded by <code>resource == null</code> never allows anything at all.</p>
+<p>The rest of the idiom agrees on both sides. <code>allow update: if resource != null</code> behaves the same in pyric and Firebase, and a create against an object
+that already exists is denied by both. Only the case the guard exists for,
+the genuinely new object, differs.</p>
+<h3 id="what-you-should-do">What you should do</h3>
+<p>Delete the existence check. Storage rules already give it to you: <code>create</code>
+only fires when there is no existing object, and <code>update</code> only fires when
+there is one. The verb is the existence check.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="plaintext"><code><span class="line"><span>match /uploads/{fileId} {</span></span>
+<span class="line"><span>  allow create: if request.auth != null;</span></span>
+<span class="line"><span>  allow update: if request.auth != null</span></span>
+<span class="line"><span>                &#x26;&#x26; resource.metadata.owner == request.auth.uid;</span></span>
+<span class="line"><span>}</span></span></code></pre>
+<p>Do not reference <code>resource</code> anywhere inside a <code>create</code> rule. Not
+<code>resource == null</code>, not <code>resource != null</code>, not <code>resource.size</code>. There is no
+object to read, and in production reading it errors, which denies. Put your
+create conditions on <code>request</code> (<code>request.auth</code>, <code>request.resource.size</code>,
+<code>request.resource.contentType</code>) and your overwrite conditions on <code>update</code>,
+where <code>resource</code> is real.</p>
+<p>The same bug exists in the Firestore engine and is tracked in
+<a href="https://github.com/davideast/pyric/issues/205" target="_blank" rel="noopener noreferrer" class="external-link">#205</a>, where <code>resource</code> is
+non-null for a missing document and existence guards written as
+<code>resource != null</code> allow in pyric. Both are the same defect: pyric models the
+absent-object value the way the documentation reads, and production does
+something else. Until it closes, pyric keeps allowing this create.</p>
+<h2 id="everything-else-in-the-storage-evaluator-matches-firebase">Everything else in the storage evaluator matches Firebase</h2>
+<p>Verified case for case against production captures, with no pinned
+divergence:</p>
+<ul>
+<li>Verb grants. <code>read</code> expands to <code>get</code> and <code>list</code>, <code>write</code> expands to
+<code>create</code>, <code>update</code>, and <code>delete</code>, single verbs and comma-separated verb
+lists grant exactly what they name, and anything ungranted is denied.</li>
+<li><code>resource</code> object identity and time fields: <code>name</code>, <code>bucket</code>,
+<code>timeCreated</code>, <code>updated</code>. Extension guards, freshness windows,
+immutability checks, and absent-property negation all agree.</li>
+<li><code>resource.metadata</code> and <code>request.resource.metadata</code> reads, including
+metadata-driven verb grants and arithmetic on metadata values.</li>
+<li><code>request.time</code>, timestamp comparison, and duration arithmetic.</li>
+<li>User-defined functions and <code>let</code> bindings, including their scoping.</li>
+<li><code>matches()</code> regular expressions.</li>
+<li>Cross-service lookups: <code>firestore.get()</code> and <code>firestore.exists()</code>.</li>
+</ul>
+<h2 id="how-this-is-checked-and-how-to-check-it-yourself">How this is checked, and how to check it yourself</h2>
+<p>The gap above is replayed on every test run. The suite loads each captured
+production observation, runs the same ruleset and the same request through
+the local evaluator, and compares verdicts case for case.</p>
+<ul>
+<li>Suite: <code>packages/pyric/test/storage/rules-oracle-conformance.test.ts</code>.
+Run it with <code>bun test packages/pyric/test/storage/rules-oracle-conformance.test.ts</code>.</li>
+<li>Captures: <code>packages/conformance/observations/storage-rules/*.json</code>. Eight
+observations, one of which contains the divergent case.</li>
+<li>The gap’s key: observation <code>rules-storage-verbs-umbrella-granular</code>, case
+<code>create allowed when object does not exist (resource == null)</code>. Production
+DENY, evaluator ALLOW.</li>
+<li>Ruleset and cases: <code>packages/conformance/rules-corpus/storage/verbs-umbrella-granular.ts</code>.</li>
+</ul>
+<p>The gap is pinned in the suite’s <code>KNOWN_DIVERGENCES</code> table, which asserts
+both sides: production’s captured verdict and the evaluator’s live verdict.
+The suite is green while the gap is exactly as described. It fails the moment
+either side moves, including when someone fixes the evaluator, which forces
+the fix to delete the pin instead of landing silently beside a stale one.</p>
+<p>Before it was pinned it was live-probed against production twice, once with
+the <code>resource</code> field omitted from the request and once with it sent
+explicitly as null. Both are how the harness encodes “no existing object” on
+the wire. Both denied identically with the same null value error, which rules
+out a capture bug in the harness.</p>
+<h2 id="where-to-look-next">Where to look next</h2>
+<ul>
+<li><a href="../pyric-storage-reference-rules-subset/">Storage rules subset</a> for the grammar the evaluator
+supports.</li>
+<li><a href="../pyric-storage-explanation-implementation-scope/">Implementation scope and deferred features</a>.</li>
+<li><a href="../pyric-storage-compat/">Compatibility matrix</a> for the row-by-row registry.</li>
+<li><a href="../pyric-rules-reference-conformance-gaps/">Firestore rules gaps</a> for the
+same page on the Firestore side.</li>
+</ul>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#how-to-read-severity">How to read severity</a> </li><li data-depth="2"> <a href="#resource--null-allows-a-create-in-pyric-that-firebase-denies">resource == null allows a create in pyric that Firebase denies</a> </li><li data-depth="3"> <a href="#what-you-would-write">What you would write</a> </li><li data-depth="3"> <a href="#what-happens">What happens</a> </li><li data-depth="3"> <a href="#what-you-should-do">What you should do</a> </li><li data-depth="2"> <a href="#everything-else-in-the-storage-evaluator-matches-firebase">Everything else in the storage evaluator matches Firebase</a> </li><li data-depth="2"> <a href="#how-this-is-checked-and-how-to-check-it-yourself">How this is checked, and how to check it yourself</a> </li><li data-depth="2"> <a href="#where-to-look-next">Where to look next</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-storage-reference-conformance-gaps.md ADDED Viewed

@@ -0,0 +1,171 @@
+# Storage rules gaps: where pyric and Firebase disagree
+A gap is a rule that gets one answer from pyric and a different answer from
+Firebase. You write the rule once. pyric allows the request and Firebase
+denies it, or the other way round. The rule you tested is not the rule you
+shipped.
+Every gap on this page was captured from the production Rules Test API, not
+inferred. There is one gap in the storage evaluator today. It affects the
+create-if-absent idiom, which is common. Read that one section and you are
+done.
+## How to read severity
+Every gap has two facts. A single label hides one of them, so this page
+reports both.
+**Fidelity** is the direction of the disagreement. Either pyric allows where
+Firebase denies, or pyric denies where Firebase allows. Either way the verdict
+you get locally is not the verdict you get in production, and the whole point
+of a local mirror is that the two match.
+**Production impact** is whether the gap lets a request through in production
+that should not get through. It follows from the direction.
+- **pyric allows, Firebase denies.** Production is stricter than pyric. Nothing
+  pyric wrongly allowed reaches production, so there is no production hole. The
+  cost is trust: a local ALLOW you relied on is wrong, and a legitimate
+  operation you validated locally can be refused in production.
+- **pyric denies, Firebase allows.** Production is more permissive than pyric.
+  A request your local mirror refused can succeed in production. This is the
+  direction that ships a hole: a rule you tested as blocking may not block.
+Read both. A broken verdict with no production hole is still a broken verdict,
+and a narrow trigger in the permissive direction is still the direction that
+leaks.
+## `resource == null` allows a create in pyric that Firebase denies
+**Fidelity:** pyric allows, Firebase denies.
+**Production impact:** no attacker reaches production, because Firebase denies
+this create too. But the companion cases match on both sides (an update, and a
+create over an object that already exists), so a real ruleset that guards writes
+with `resource == null` / `resource != null` still denies unauthorized writes in
+production. Only the case the guard exists for, the genuinely new object,
+differs: locally it uploads, in production it is refused.
+### What you would write
+The create-if-absent guard. Anyone may upload a new object, nobody may
+overwrite one:
+```
+rules_version = '2';
+service firebase.storage {
+  match /b/{bucket}/o {
+    match /uploads/{fileId} {
+      allow create: if resource == null;
+      allow update: if resource != null;
+    }
+  }
+}
+```
+### What happens
+Upload to `uploads/report.pdf` when no such object exists yet:
+```ts
+import { getStorage, ref, uploadBytes } from 'pyric/storage';
+await uploadBytes(ref(getStorage(app), 'uploads/report.pdf'), bytes);
+```
+In pyric the create is ALLOWED. `resource` is null before the object exists,
+so `resource == null` is true and the rule passes.
+In Firebase the create is DENIED. Firebase never evaluates the comparison.
+Reading `resource` on a create where no object exists raises a null value
+error, the expression errors, and an errored expression denies.
+Your rule does not do what you think it does. Locally every first upload
+succeeds. In production every first upload is refused, and a `create` rule
+guarded by `resource == null` never allows anything at all.
+The rest of the idiom agrees on both sides. `allow update: if resource !=
+null` behaves the same in pyric and Firebase, and a create against an object
+that already exists is denied by both. Only the case the guard exists for,
+the genuinely new object, differs.
+### What you should do
+Delete the existence check. Storage rules already give it to you: `create`
+only fires when there is no existing object, and `update` only fires when
+there is one. The verb is the existence check.
+```
+match /uploads/{fileId} {
+  allow create: if request.auth != null;
+  allow update: if request.auth != null
+                && resource.metadata.owner == request.auth.uid;
+}
+```
+Do not reference `resource` anywhere inside a `create` rule. Not
+`resource == null`, not `resource != null`, not `resource.size`. There is no
+object to read, and in production reading it errors, which denies. Put your
+create conditions on `request` (`request.auth`, `request.resource.size`,
+`request.resource.contentType`) and your overwrite conditions on `update`,
+where `resource` is real.
+The same bug exists in the Firestore engine and is tracked in
+[#205](https://github.com/davideast/pyric/issues/205), where `resource` is
+non-null for a missing document and existence guards written as
+`resource != null` allow in pyric. Both are the same defect: pyric models the
+absent-object value the way the documentation reads, and production does
+something else. Until it closes, pyric keeps allowing this create.
+## Everything else in the storage evaluator matches Firebase
+Verified case for case against production captures, with no pinned
+divergence:
+- Verb grants. `read` expands to `get` and `list`, `write` expands to
+  `create`, `update`, and `delete`, single verbs and comma-separated verb
+  lists grant exactly what they name, and anything ungranted is denied.
+- `resource` object identity and time fields: `name`, `bucket`,
+  `timeCreated`, `updated`. Extension guards, freshness windows,
+  immutability checks, and absent-property negation all agree.
+- `resource.metadata` and `request.resource.metadata` reads, including
+  metadata-driven verb grants and arithmetic on metadata values.
+- `request.time`, timestamp comparison, and duration arithmetic.
+- User-defined functions and `let` bindings, including their scoping.
+- `matches()` regular expressions.
+- Cross-service lookups: `firestore.get()` and `firestore.exists()`.
+## How this is checked, and how to check it yourself
+The gap above is replayed on every test run. The suite loads each captured
+production observation, runs the same ruleset and the same request through
+the local evaluator, and compares verdicts case for case.
+- Suite: `packages/pyric/test/storage/rules-oracle-conformance.test.ts`.
+  Run it with `bun test packages/pyric/test/storage/rules-oracle-conformance.test.ts`.
+- Captures: `packages/conformance/observations/storage-rules/*.json`. Eight
+  observations, one of which contains the divergent case.
+- The gap's key: observation `rules-storage-verbs-umbrella-granular`, case
+  `create allowed when object does not exist (resource == null)`. Production
+  DENY, evaluator ALLOW.
+- Ruleset and cases: `packages/conformance/rules-corpus/storage/verbs-umbrella-granular.ts`.
+The gap is pinned in the suite's `KNOWN_DIVERGENCES` table, which asserts
+both sides: production's captured verdict and the evaluator's live verdict.
+The suite is green while the gap is exactly as described. It fails the moment
+either side moves, including when someone fixes the evaluator, which forces
+the fix to delete the pin instead of landing silently beside a stale one.
+Before it was pinned it was live-probed against production twice, once with
+the `resource` field omitted from the request and once with it sent
+explicitly as null. Both are how the harness encodes "no existing object" on
+the wire. Both denied identically with the same null value error, which rules
+out a capture bug in the harness.
+## Where to look next
+- [Storage rules subset](../pyric-storage-reference-rules-subset/) for the grammar the evaluator
+  supports.
+- [Implementation scope and deferred features](../pyric-storage-explanation-implementation-scope/).
+- [Compatibility matrix](../pyric-storage-compat/) for the row-by-row registry.
+- [Firestore rules gaps](../pyric-rules-reference-conformance-gaps/) for the
+  same page on the Firestore side.

package/dist/serve/docs-ui/docs/pyric-storage-reference-error-codes/index.html ADDED Viewed

@@ -0,0 +1,37 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Error codes · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/" aria-current="true"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/" aria-current="true"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-storage/">pyric / storage</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Error codes</span> </li> </ol> </nav>  <article class="prose">  <h1 id="error-codes">Error codes</h1>
+<p>Operations through <code>pyric/storage</code> throw errors with Firebase-aligned <code>code</code> properties, <code>'storage/&#x3C;noun>'</code>. Catch by code.</p>
+<h2 id="common-codes">Common codes</h2>
+<h3 id="storageunauthenticated"><code>'storage/unauthenticated'</code></h3>
+<p>The operation requires an authenticated user (rule expects <code>request.auth != null</code>) but the context’s auth is <code>null</code>.</p>
+<h3 id="storageunauthorized"><code>'storage/unauthorized'</code></h3>
+<p>The operation has an authenticated user but rules denied it.</p>
+<h3 id="storageobject-not-found"><code>'storage/object-not-found'</code></h3>
+<p><code>getBytes</code>, <code>getBlob</code>, <code>getMetadata</code>, <code>updateMetadata</code> against a path with no stored object.</p>
+<h3 id="storagequota-exceeded"><code>'storage/quota-exceeded'</code></h3>
+<p>Reserved on the <code>StorageErrorCode</code> union for upstream parity. The sandbox does <strong>not</strong> raise it for <code>maxDownloadSizeBytes</code> — that path truncates like production. Bucket-level quota is not modeled.</p>
+<h3 id="storageinvalid-argument"><code>'storage/invalid-argument'</code></h3>
+<p>A function argument failed validation. Common cases: empty path, malformed string format in <code>uploadString</code>, non-string <code>contentType</code>.</p>
+<h2 id="branching">Branching</h2>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">try</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">  await</span><span style="color:#61AFEF"> getBlob</span><span style="color:#ABB2BF">(</span><span style="color:#61AFEF">ref</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">storage</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'sessions/n1'</span><span style="color:#ABB2BF">));</span></span>
+<span class="line"><span style="color:#ABB2BF">} </span><span style="color:#C678DD">catch</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">e</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">  if</span><span style="color:#ABB2BF"> (</span><span style="color:#E06C75">e</span><span style="color:#56B6C2"> &#x26;&#x26;</span><span style="color:#C678DD"> typeof</span><span style="color:#E06C75"> e</span><span style="color:#56B6C2"> ===</span><span style="color:#98C379"> 'object'</span><span style="color:#56B6C2"> &#x26;&#x26;</span><span style="color:#98C379"> 'code'</span><span style="color:#C678DD"> in</span><span style="color:#E06C75"> e</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">    switch</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">e</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">code</span><span style="color:#ABB2BF">) {</span></span>
+<span class="line"><span style="color:#C678DD">      case</span><span style="color:#98C379"> 'storage/object-not-found'</span><span style="color:#ABB2BF">:</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">        // missing</span></span>
+<span class="line"><span style="color:#C678DD">        break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">      case</span><span style="color:#98C379"> 'storage/unauthorized'</span><span style="color:#ABB2BF">:</span></span>
+<span class="line"><span style="color:#C678DD">      case</span><span style="color:#98C379"> 'storage/unauthenticated'</span><span style="color:#ABB2BF">:</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">        // denied</span></span>
+<span class="line"><span style="color:#C678DD">        break</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#C678DD">      default</span><span style="color:#ABB2BF">:</span></span>
+<span class="line"><span style="color:#C678DD">        throw</span><span style="color:#E06C75"> e</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">    }</span></span>
+<span class="line"><span style="color:#ABB2BF">  } </span><span style="color:#C678DD">else</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#C678DD">    throw</span><span style="color:#E06C75"> e</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#ABB2BF">  }</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<p>The sandbox throws <code>StorageError</code>, an <code>Error</code> subclass whose <code>.code</code> carries the Firebase-shaped value. Production code imports <code>firebase/storage</code> directly and receives Firebase’s own error class; branching on <code>.code</code> works in both environments without coupling application code to either constructor.</p>
+<h2 id="what-the-sandbox-does-not-emit">What the sandbox does not emit</h2>
+<p>The sandbox emits only <code>unauthenticated</code>, <code>unauthorized</code>, <code>object-not-found</code>, <code>quota-exceeded</code>, <code>invalid-root-operation</code>, <code>invalid-format</code>, and <code>invalid-argument</code>. Network-bound codes such as <code>canceled</code>, <code>retry-limit-exceeded</code>, <code>app-deleted</code>, and <code>server-file-wrong-size</code> do not apply.</p>
+<p>If application error handling branches on a network-only code, that branch will not fire while the package swap is active. Exercise it in a production-integration test against Firebase.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#common-codes">Common codes</a> </li><li data-depth="3"> <a href="#storageunauthenticated">&#39;storage/unauthenticated&#39;</a> </li><li data-depth="3"> <a href="#storageunauthorized">&#39;storage/unauthorized&#39;</a> </li><li data-depth="3"> <a href="#storageobject-not-found">&#39;storage/object-not-found&#39;</a> </li><li data-depth="3"> <a href="#storagequota-exceeded">&#39;storage/quota-exceeded&#39;</a> </li><li data-depth="3"> <a href="#storageinvalid-argument">&#39;storage/invalid-argument&#39;</a> </li><li data-depth="2"> <a href="#branching">Branching</a> </li><li data-depth="2"> <a href="#what-the-sandbox-does-not-emit">What the sandbox does not emit</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-storage-reference-error-codes.md ADDED Viewed

@@ -0,0 +1,57 @@
+# Error codes
+Operations through `pyric/storage` throw errors with Firebase-aligned `code` properties, `'storage/<noun>'`. Catch by code.
+## Common codes
+### `'storage/unauthenticated'`
+The operation requires an authenticated user (rule expects `request.auth != null`) but the context's auth is `null`.
+### `'storage/unauthorized'`
+The operation has an authenticated user but rules denied it.
+### `'storage/object-not-found'`
+`getBytes`, `getBlob`, `getMetadata`, `updateMetadata` against a path with no stored object.
+### `'storage/quota-exceeded'`
+Reserved on the `StorageErrorCode` union for upstream parity. The sandbox does **not** raise it for `maxDownloadSizeBytes` — that path truncates like production. Bucket-level quota is not modeled.
+### `'storage/invalid-argument'`
+A function argument failed validation. Common cases: empty path, malformed string format in `uploadString`, non-string `contentType`.
+## Branching
+```ts
+try {
+  await getBlob(ref(storage, 'sessions/n1'));
+} catch (e) {
+  if (e && typeof e === 'object' && 'code' in e) {
+    switch (e.code) {
+      case 'storage/object-not-found':
+        // missing
+        break;
+      case 'storage/unauthorized':
+      case 'storage/unauthenticated':
+        // denied
+        break;
+      default:
+        throw e;
+    }
+  } else {
+    throw e;
+  }
+}
+```
+The sandbox throws `StorageError`, an `Error` subclass whose `.code` carries the Firebase-shaped value. Production code imports `firebase/storage` directly and receives Firebase's own error class; branching on `.code` works in both environments without coupling application code to either constructor.
+## What the sandbox does not emit
+The sandbox emits only `unauthenticated`, `unauthorized`, `object-not-found`, `quota-exceeded`, `invalid-root-operation`, `invalid-format`, and `invalid-argument`. Network-bound codes such as `canceled`, `retry-limit-exceeded`, `app-deleted`, and `server-file-wrong-size` do not apply.
+If application error handling branches on a network-only code, that branch will not fire while the package swap is active. Exercise it in a production-integration test against Firebase.