@omega.js/backend 0.1.0

package/templates/database.rules.json

@@ -0,0 +1,82 @@
+{
+  "rules": {
+    // ========== OMEGA Rules (v0.0.0) ==========
+
+    // Sessions rules
+    "sessions": {
+      ".read": false,
+      ".write": false,
+			"$room": {
+        ".read": "
+        	(auth.uid != null && query.equalTo == auth.uid)
+        ",
+        ".write": false,
+        ".indexOn": ["uid"],
+        "$id": {
+          ".read": "
+          	// Allowed if user is authenticated AND is the owner of the doc
+          	(auth != null && auth.uid == data.child('uid').val())
+            // Allowed if uid is equal to the doc id [LEGACY FOR SOMIIBO]
+            || (auth != null && auth.uid == $id)
+          	// Allowed if user is not authenticated AND is the doc has no owner
+          	|| (auth == null && (data.child('uid').val() == ''))
+          ",
+          ".write": "
+          	// Allowed if the user is authenticated AND is the owner of the existing doc
+          	(auth != null && auth.uid == data.child('uid').val())
+          	// Allowed if the user is authenticated AND is the owner of the new doc
+          	|| (auth != null && auth.uid == newData.child('uid').val())
+            // Allowed if the user is authenticated AND is the owner of the existing doc
+          	|| (auth != null && auth.uid == data.child('uid').val())
+            // Allowed if uid is equal to the doc id [LEGACY FOR SOMIIBO]
+            || (auth != null && auth.uid == $id)
+            // Allowed if the existing doc has no owner
+          	|| (data.child('uid').val() == '')
+          	// Allowed if the new doc has no owner
+          	|| (newData.child('uid').val() == '')
+            // Allowed if it's a delete
+          	|| (!newData.exists())
+          ",
+      	}
+      }
+    },
+    "gatherings": {
+      ".read": false,
+      ".write": false,
+			"$room": {
+        ".read": "
+        	(auth.uid != null && query.equalTo == auth.uid)
+        ",
+        ".write": false,
+        ".indexOn": ["uid"],
+        "$id": {
+          ".read": "
+          	// Allowed if user is authenticated AND is the owner of the doc
+          	(auth != null && auth.uid == data.child('uid').val())
+            // Allowed if uid is equal to the doc id [LEGACY FOR SOMIIBO]
+            || (auth != null && auth.uid == $id)
+          	// Allowed if user is not authenticated AND is the doc has no owner
+          	|| (auth == null && (data.child('uid').val() == ''))
+          ",
+          ".write": "
+          	// Allowed if the user is authenticated AND is the owner of the existing doc
+          	(auth != null && auth.uid == data.child('uid').val())
+          	// Allowed if the user is authenticated AND is the owner of the new doc
+          	|| (auth != null && auth.uid == newData.child('uid').val())
+            // Allowed if the user is authenticated AND is the owner of the existing doc
+          	|| (auth != null && auth.uid == data.child('uid').val())
+            // Allowed if uid is equal to the doc id [LEGACY FOR SOMIIBO]
+            || (auth != null && auth.uid == $id)
+            // Allowed if the existing doc has no owner
+          	|| (data.child('uid').val() == '')
+          	// Allowed if the new doc has no owner
+          	|| (newData.child('uid').val() == '')
+            // Allowed if it's a delete
+          	|| (!newData.exists())
+          ",
+      	}
+      }
+    },
+    // ========== End OMEGA Rules ==========
+  }
+}

package/templates/firebase.json

@@ -0,0 +1,67 @@
+{
+  "hosting": {
+    "public": "dist/public",
+    "ignore": [
+      "firebase.json",
+      "**/.*",
+      "**/node_modules/**"
+    ],
+    "rewrites": [
+      {
+        "source": "{/omega,/omega/**,/backend-manager,/backend-manager/**,/mcp,/mcp/**,/.well-known/oauth-protected-resource,/.well-known/oauth-authorization-server,/authorize,/token,/register}",
+        "function": "omega_api"
+      }
+    ]
+  },
+  "functions": [
+    {
+      "source": "dist",
+      "codebase": "default",
+      "ignore": [
+        "node_modules",
+        ".git",
+        "firebase-debug.log",
+        "firebase-debug.*.log",
+        "deploy.log"
+      ]
+    }
+  ],
+  "firestore": {
+    "rules": "dist/firestore.rules",
+    "indexes": "firestore.indexes.json"
+  },
+  "database": {
+    "rules": "database.rules.json"
+  },
+  "storage": {
+    "rules": "storage.rules"
+  },
+  "emulators": {
+    "auth": {
+      "port": 9099
+    },
+    "functions": {
+      "port": 5001
+    },
+    "firestore": {
+      "port": 8080
+    },
+    "database": {
+      "port": 9000
+    },
+    "hosting": {
+      "port": 5002
+    },
+    "storage": {
+      "port": 9199
+    },
+    "ui": {
+      "enabled": true,
+      "port": 4050
+    },
+    "pubsub": {
+      "port": 8085
+    },
+    "singleProjectMode": true
+  }
+}

package/templates/firestore.framework.rules

@@ -0,0 +1,191 @@
+// ============================================================================
+// @omega.js/backend — the FRAMEWORK half of the Firestore rules.
+//
+// This file ships INSIDE @omega.js/backend and never exists in a brand repo.
+// `omega build` compiles it together with the brand's own firestore.rules into
+// dist/firestore.rules — the artifact firebase.json points the emulator AND
+// `firebase deploy` at (src/cli/utils/compile-rules.js).
+//
+// MERGE-BY-MATCH ([#353](https://github.com/Omega-JS-Stack/omega/issues/353)):
+// Firestore ORs `allow` across sibling match blocks, so a brand's own
+// `match /users/{uid}` could only ever WIDEN what this file allows. So the
+// compiler MERGES it instead — a brand block whose path matches one below
+// (wildcard names normalized) folds in, and for an op both blocks declare the
+// brand's condition is ANDed onto the framework's. A brand writes ordinary
+// rules; there are no hook functions any more (they retired in rules v3).
+//
+// Both halves land in the SAME `match /databases/{database}/documents` scope,
+// so every helper below is callable from a brand's rules, in either direction.
+//
+// NAMING: `is*` is a PREDICATE about the caller or about this write, and reads
+// as a sentence in a rule (`isUser(uid)`, `isWritingField('xp')`); `get*` hands
+// back a VALUE to compare against (`getAuthUid()`, `getIncomingData()`).
+//
+// COST: every helper here is free except getRoles(), which bills ONE document
+// read per call — and `isAdmin()` is built on it, so the lock-by-default block
+// below means even a denied request pays for one read.
+// ============================================================================
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    // Lock by default
+    match /{document=**} {
+      allow read, write: if isAdmin();
+    }
+
+    // Protect user account data. A brand TIGHTENS this by writing its own
+    // `match /users/{uid}` block — the compiler ANDs its condition onto the
+    // ops below. DELETE is deliberately not declared: a user document is
+    // removed by the auth trigger, never by its owner, and naming the two ops
+    // this rule MEANS keeps a client delete denied by the admin catch-all
+    // above instead of by an evaluation error (a delete carries no incoming
+    // data for the field guard to read).
+    match /users/{uid} {
+      allow read: if isUser(uid);
+      allow create, update: if isUser(uid) && !isWritingFrameworkField();
+    }
+
+    // Protect notification data — the doc id IS the push token, a high-entropy
+    // capability: knowing it proves possession of the device. Point reads/updates ride
+    // that capability; list is denied so tokens can never be harvested by query; owner
+    // may only be null (anonymous subscribe) or the caller's own uid.
+    match /notifications/{token} {
+      allow get: if true;
+      allow list: if false;
+      allow create: if getIncomingData().token == token
+        && (getIncomingData().owner == null || (isAuthenticated() && getIncomingData().owner == getAuthUid()));
+      // `getIncomingData().token == token` is the malformed-doc guard: a legacy-era
+      // doc whose stored token never matched its id is client-read-only, never
+      // updatable ([#288](https://github.com/Omega-JS-Stack/omega/issues/288)).
+      // The `== getExistingData().token` clause keeps the field immutable.
+      allow update: if getIncomingData().token == token
+        && getIncomingData().token == getExistingData().token
+        && (getIncomingData().owner == null || (isAuthenticated() && getIncomingData().owner == getAuthUid()));
+    }
+
+    // Protect abandoned cart data. NOT `isOwner()`: this rule pins the owner
+    // the write CARRIES to the doc id, on the update as well as the create, so
+    // an owner cannot hand their own cart to somebody else. `isOwner()` asks
+    // the other question (does the STORED owner name the caller), which an
+    // owner rewriting the field would still satisfy.
+    match /payments-carts/{uid} {
+      allow create, update: if isUser(uid)
+        && getIncomingData().owner == uid
+        && getIncomingData().status == 'pending';
+      allow read: if isUser(uid);
+    }
+
+    // ========== Auth ==========
+    function getAuthEmail() {
+      return request.auth.token.email;
+    }
+    function getAuthUid() {
+      return request.auth.uid;
+    }
+    function isAuthenticated() {
+      return request.auth != null;
+    }
+    // The caller IS `identity` — a uid or an email, since a doc id is one or
+    // the other across the framework's collections. The EMAIL arm requires a
+    // VERIFIED token: Firebase Auth lets anyone sign up claiming any address,
+    // so an unproven claim must never match an email-keyed document. The uid
+    // arm needs no such gate — a uid is Firebase Auth's own value.
+    function isUser(identity) {
+      return isAuthenticated() && (getAuthUid() == identity || (isEmailVerified() && getAuthEmail() == identity));
+    }
+    // The caller owns THIS doc: its `owner` field names them. The STORED owner
+    // once the document exists — so an update can never hand ownership to
+    // whoever is writing — and the INCOMING one on a create, where there is no
+    // stored document to own yet. That is what makes the answer mean the same
+    // thing on every op. `.get()` (not `.owner`) because reading a key a map
+    // does not carry is an error, and an error denies the whole rule.
+    function isOwner() {
+      return isUser(resource == null
+        ? getIncomingData().get('owner', null)
+        : getExistingData().get('owner', null));
+    }
+
+    // ========== Account ==========
+    // The get() below bills ONE document read, every time it is called.
+    function getRoles() {
+      return get(/databases/$(database)/documents/users/$(request.auth.uid)).data.roles;
+    }
+    function isAdmin() {
+      return getRoles().admin == true;
+    }
+    // The AUTH TOKEN, never a stored field: `users/{uid}.verifications` is
+    // written by nothing server-side, so reading it would only ever trust a
+    // value the client planted. The token claim is Firebase Auth's, it cannot
+    // be forged, it costs no read, and it is right on the first request. Read
+    // through `.get()` because a token without an email (phone or anonymous
+    // sign-in) carries no such claim at all, and reading a key a map does not
+    // carry is an error that would deny the whole rule.
+    function isEmailVerified() {
+      return isAuthenticated() && request.auth.token.get('email_verified', false) == true;
+    }
+
+    // ========== Document data ==========
+    // [READ] Data that exists on the Firestore document. `resource` is null on
+    // a CREATE, and reading through a null errors (which denies the rule), so
+    // an absent document reads as the empty map — that is what makes every
+    // field helper below correct on create as well as update.
+    function getExistingData() {
+      return resource == null ? {} : resource.data;
+    }
+    // [WRITE] Data that is sent to a Firestore document
+    function getIncomingData() {
+      return request.resource.data;
+    }
+
+    // ========== Field writes ==========
+    // Is this write touching any of `fields`? TOP-LEVEL keys: protecting
+    // `xp.total` means listing `'xp'`. Counts creations, value changes and
+    // removals; writing a key back with the SAME value is not a write.
+    function isWritingAny(fields) {
+      return getIncomingData().diff(getExistingData()).affectedKeys().hasAny(fields);
+    }
+    function isWritingField(field) {
+      return isWritingAny([field]);
+    }
+    // The two halves of a write, when a rule needs to tell them apart.
+    function isCreatingField(field) {
+      return !(field in getExistingData()) && field in getIncomingData();
+    }
+    function isUpdatingField(field) {
+      return field in getExistingData() && field in getIncomingData() && getExistingData()[field] != getIncomingData()[field];
+    }
+
+    // The user-doc keys the FRAMEWORK owns: server-written, never a client's.
+    // A brand protects keys of its own by tightening `match /users/{uid}` in
+    // its own firestore.rules — e.g. `allow create, update: if !isWritingAny(['xp']);`.
+    // `verifications` is on the list as a RESERVED name: nothing writes it
+    // today, and a client planting one must never look like server truth.
+    // `trackingConsent` and `attribution` sit beside `consent` for the same
+    // reason it does: both reach the user doc through the signup route ONLY
+    // (the client SENDS them in the payload; the server is what writes them),
+    // so a direct client write could only ever be a forged consent answer or a
+    // rewritten campaign credit — the two records nobody may edit after the fact.
+    // `usage` covers `usage.overrides` too — the admin-granted extra credits a
+    // counted feature's limit resolves against — and `owns` names the documents
+    // a feature's counters mirror onto, so a client that could write either
+    // would be granting itself quota or aiming another account's counters
+    // ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)).
+    // `connections` is a CREDENTIAL STORE, not a record: the account page renders
+    // whatever sits there as a live connection, and the status route hands
+    // `connections.<provider>.token.refresh_token` straight to the provider — so a
+    // client write forges a connection AND plants a token the server then
+    // spends ([#771](https://github.com/Omega-JS-Stack/omega/issues/771)).
+    // `activity` is the sign-in/security trail (IP, user agent, locale) the
+    // before-signin auth event writes; a client that could write it would be
+    // editing its own audit record.
+    function isWritingFrameworkField() {
+      return isWritingAny(['auth', 'connections', 'roles', 'flags', 'subscription', 'affiliate', 'api', 'metadata', 'activity', 'usage', 'owns', 'consent', 'trackingConsent', 'attribution', 'verifications']);
+    }
+
+    // ========== Resources ==========
+    // https://fireship.io/snippets/firestore-rules-recipes/
+    // https://github.com/jaysquared/atom-firestore-grammar
+    // https://fireship.io/courses/firestore-data-modeling/models-roles/
+    // https://firebase.google.com/docs/firestore/security/test-rules-emulator
+  }
+}

package/templates/firestore.indexes.json

@@ -0,0 +1,4 @@
+{
+  "indexes": [],
+  "fieldOverrides": []
+}

package/templates/firestore.rules

@@ -0,0 +1,59 @@
+// ============================================================================
+// YOUR Firestore rules. This file is the SOURCE and it is yours — @omega.js/backend
+// never rewrites the rules you write here.
+//
+// `omega build` COMPILES this file together with the framework half into
+// dist/firestore.rules, and firebase.json points the emulator AND
+// `firebase deploy` at that compiled artifact. Never edit the compiled file.
+//
+//   Framework half : node_modules/@omega.js/backend/templates/firestore.framework.rules
+//   Compiled output: dist/firestore.rules  (GENERATED — do not edit)
+//
+// MERGE-BY-MATCH — how you TIGHTEN a framework rule. Firestore ORs `allow`
+// across sibling match blocks, so a second `match /users/{uid}` could only ever
+// widen access. Instead, a match block here whose PATH matches a framework
+// block's (wildcard names do not have to agree) is MERGED into it: for an op
+// both blocks declare, your condition is ANDed onto the framework's.
+//
+//   you write here          match /users/{userId} {
+//                             allow create, update: if !isWritingAny(['xp']) && isEmailVerified();
+//                           }
+//   the framework ships     match /users/{uid} {
+//                             allow create, update: if isUser(uid) && !isWritingFrameworkField();
+//                           }
+//   dist/firestore.rules    match /users/{uid} {
+//                             allow create, update: if isUser(uid) && !isWritingFrameworkField() && (!isWritingAny(['xp']) && isEmailVerified());
+//                           }
+//
+// Ops pair by NAME, so name the same ones the framework does (`allow write`
+// beside its `allow create, update` would WIDEN, not tighten — the compiler
+// says so out loud). An op ONLY you declare is appended as written (that op
+// widens, as sibling blocks always did); a nested match of yours splices in; a
+// path the framework does not define is yours alone and passes through
+// untouched.
+//
+// Both halves land in the SAME `match /databases/{database}/documents` scope,
+// so your rules may call ANY framework helper — declaration order does not
+// matter. `is*` asks a question, `get*` hands back a value:
+//
+//   isAuthenticated()   isUser(id)          isOwner()
+//   isAdmin()           isEmailVerified()
+//   isWritingAny(list)  isWritingField(f)   isCreatingField(f) isUpdatingField(f)
+//   getAuthUid()        getAuthEmail()      getRoles()
+//   getExistingData()   getIncomingData()
+//
+// Fields are TOP-LEVEL: protecting `xp.total` means listing `'xp'`.
+// See the framework half for the full list and what each one reads (`getRoles()`
+// bills a document read per call, and so does every `isAdmin()`; the rest are
+// free).
+// ============================================================================
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    // ─── Your rules ──────────────────────────────────────────────────────────
+    // match /posts/{id} {
+    //   allow read: if true;
+    //   allow write: if isAdmin();
+    // }
+  }
+}

package/templates/index.js

@@ -0,0 +1,12 @@
+/*
+  Initialize
+*/
+const Manager = (new (require('@omega.js/backend'))).init(exports, {
+});
+const { functions } = Manager.libraries;
+
+/*
+  Routes
+  Add custom routes below. Built-in routes (auth, payments, newsletters,
+  usage, etc.) are registered automatically by OMEGA Backend.
+*/

package/templates/public/404.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>404 Error Page</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
+  </head>
+
+  <body>
+    <div class="d-flex align-items-center justify-content-center vh-100">
+      <div class="text-center">
+        <h1 class="display-1 fw-bold">404</h1>
+
+        <p class="fs-3"> <span class="text-danger">Opps!</span> Page not found.</p>
+
+        <p class="lead">
+          The page you're looking for doesn't exist.
+        </p>
+
+        <a href="{url}" class="btn btn-primary">Go Home</a>
+      </div>
+    </div>
+  </body>
+</html>

package/templates/public/index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Welcome</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
+  </head>
+
+  <body>
+    <div class="d-flex align-items-center justify-content-center vh-100">
+      <div class="text-center">
+        <h1 class="display-1 fw-bold">Welcome!</h1>
+
+        <p class="lead">
+          This is an internal page, please return to our main website
+        </p>
+
+        <a href="{url}" class="btn btn-primary">Go Home</a>
+      </div>
+    </div>
+  </body>
+</html>

package/templates/remoteconfig.template.json

@@ -0,0 +1 @@
+{}

package/templates/storage-lifecycle-config-1-day.json

@@ -0,0 +1,9 @@
+{
+  "rule":
+  [
+    {
+      "action": {"type": "Delete"},
+      "condition": {"age": 1}
+    }
+  ]
+}

package/templates/storage-lifecycle-config-30-days.json

@@ -0,0 +1,9 @@
+{
+  "rule":
+  [
+    {
+      "action": {"type": "Delete"},
+      "condition": {"age": 30}
+    }
+  ]
+}

package/templates/storage.rules

@@ -0,0 +1,11 @@
+rules_version = '2';
+service firebase.storage {
+  match /b/{bucket}/o {
+    // Deny-all default: the scaffold never grants a bucket it knows nothing
+    // about. A brand that serves files from Storage opts in deliberately here,
+    // with a match block per path it actually exposes.
+    match /{allPaths=**} {
+      allow read, write: if false;
+    }
+  }
+}

package/test/_init/accounts-validation.js

@@ -0,0 +1,58 @@
+const { TEST_ACCOUNTS } = require('../../dist/test/test-accounts.js');
+
+/**
+ * Test: Account Structure Validation
+ * Verifies that all test accounts were created with the expected User helper fields
+ * This catches failures in auth:on-create before other tests run
+ */
+module.exports = {
+  description: 'Test accounts have required User structure',
+  auth: 'none',
+  timeout: 10000,
+
+  async run({ accounts, assert, firestore }) {
+    const accountIds = Object.keys(TEST_ACCOUNTS);
+
+    for (const accountId of accountIds) {
+      const account = accounts[accountId];
+
+      // Check account was fetched
+      assert.ok(account, `Account '${accountId}' should exist in accounts object`);
+      assert.ok(account.uid, `Account '${accountId}' should have uid`);
+
+      // Fetch full user doc from Firestore
+      const userDoc = await firestore.get(`users/${account.uid}`);
+
+      assert.ok(userDoc, `User doc for '${accountId}' should exist in Firestore`);
+
+      // Validate auth fields (set by on-create)
+      assert.hasProperty(userDoc, 'auth.uid', `Account '${accountId}' should have auth.uid`);
+      assert.hasProperty(userDoc, 'auth.email', `Account '${accountId}' should have auth.email`);
+
+      // Validate API fields (generated by on-create via User helper)
+      assert.hasProperty(userDoc, 'api.clientId', `Account '${accountId}' should have api.clientId`);
+      assert.hasProperty(userDoc, 'api.privateKey', `Account '${accountId}' should have api.privateKey`);
+
+      // Validate privateKey was fetched correctly
+      assert.ok(account.privateKey, `Account '${accountId}' privateKey should be fetched`);
+      assert.equal(
+        account.privateKey,
+        userDoc.api.privateKey,
+        `Account '${accountId}' fetched privateKey should match Firestore`
+      );
+
+      // Validate affiliate code (generated by on-create via User helper)
+      assert.hasProperty(userDoc, 'affiliate.code', `Account '${accountId}' should have affiliate.code`);
+
+      // Validate metadata.created (set by on-create via User helper)
+      assert.hasProperty(userDoc, 'metadata.created.timestamp', `Account '${accountId}' should have metadata.created.timestamp`);
+      assert.hasProperty(userDoc, 'metadata.created.timestampUNIX', `Account '${accountId}' should have metadata.created.timestampUNIX`);
+
+      // Validate subscription fields (merged from test account properties)
+      assert.hasProperty(userDoc, 'subscription.product.id', `Account '${accountId}' should have subscription.product.id`);
+      assert.hasProperty(userDoc, 'subscription.status', `Account '${accountId}' should have subscription.status`);
+    }
+
+    return { success: true };
+  },
+};