@iann29/rastro 0.1.0-alpha.1 → 0.1.0-alpha.11

package/docs/federation.md

@@ -0,0 +1,352 @@
+# Federated Amage Rastro dashboard
+
+This document is the protocol reference. Follow
+[`federation-setup.md`](federation-setup.md) for the executable customer-host
+installation, pairing, verification, and revocation sequence.
+
+The federated dashboard model keeps telemetry in the customer's Convex or
+Synapse deployment while a browser loaded from `amagerastro.com` subscribes
+directly to authorized host functions in that deployment.
+
+```text
+tracker -> customer deployment -> Rastro component tables
+
+amagerastro.com browser -> customer deployment -> reactive Rastro reports
+```
+
+The Amage Rastro control plane stores account and connection metadata. It does
+not need to proxy or persist the customer's analytics events.
+
+## Connector protocol v1
+
+The typed `FEDERATED_ANALYTICS_CONNECTOR_MANIFEST` constant defines the stable
+v1 contract:
+
+- protocol: `amage-rastro-analytics`
+- protocol version: `1`
+- canonical host module: `rastroFederation`
+- canonical function names and supported capabilities
+- public request, connection, range, live visitor, and journey limits
+
+The host module must be `convex/rastroFederation.ts`, so its public references
+match the function names advertised by the manifest. The generated `manifest`
+query is public because it contains only static protocol metadata. It does not
+resolve a connection or expose customer data. Compare a served manifest with
+`agent/manifest.json`'s `connector` object structurally, never as serialized
+text: the two are the same value with different key order, and a byte-for-byte
+comparison fails on a correct host.
+
+The exact generated surface is:
+
+- `manifest`
+- `connectionStatus`
+- `listSites`
+- `overview`
+- `liveVisitors`
+- `listSessions`
+- `sessionJourney`
+- `listConversions`
+- `visitorJourney`
+- `goalsReport`
+- `funnelsReport`
+- `affiliatesReport`
+- `dataCoverage`
+- `vitalsReport` (optional capability `vitals`, hosts from `alpha.6`)
+- `siteMap` (optional capability `siteMap`, hosts from `alpha.8`)
+- the configure scope (optional capability `configure`, hosts from `alpha.11`):
+  `siteSettings`, `updateSite`, `listGoals`, `upsertGoal`, `removeGoal`,
+  `listFunnels`, `upsertFunnel`, `removeFunnel`, `listAffiliates`,
+  `upsertAffiliate`, `removeAffiliate`, `retentionStatus`, `setRetentionPolicy`,
+  and `disableRetentionPolicy`
+
+Hosts from `alpha.11` also advertise the optional capability `localDays`: their
+`overview` answers a daily range that covers whole calendar days in the site's
+timezone from buckets kept in that zone, and `listSites` says per site which
+zone that is and since when the days are complete. Dashboards must not require
+the capability.
+
+There are no ingestion, owner-wide enumeration, or arbitrary host functions in
+this surface, and no write runs with a read-only token: every function of the
+configure scope requires the `analytics:configure` permission on the token
+**and** on the host's local grant, as described under
+[Configure scope](#configure-scope). The read-only goal, funnel, and affiliate
+reports include their bounded definitions, and `listConversions` returns only
+the trusted server-side conversion ledger. Browser `conversion` telemetry
+remains untrusted journey data and never enters that ledger. Journey events
+include bounded custom properties. `exposeFederatedAnalyticsApi` accepts only
+`FederatedAnalyticsAuthorizerOptions`; it does not accept or expose an arbitrary
+host `AnalyticsAuthorizer`.
+
+`connectionStatus` authenticates and resolves the authoritative connection on
+every call. Its response is deliberately redacted to status, protocol version,
+capabilities, the effective permissions, and site count. It does not return
+connection IDs, organization IDs, identity claims, or site IDs.
+
+`listSites` takes no arguments. It loads sites only from the `siteIds` in the
+validated local connection and returns `FederatedSiteSummary` values containing
+only `siteId`, `name`, `currency`, `timezone`, `cookieless`, and (hosts from
+`alpha.11`) `localDays` — `{ timezone, since }` when the host keeps the site's
+calendar days, `null` otherwise. In particular, it never returns `ownerId`,
+`domains`, or `networkId`.
+
+## Configure scope
+
+Hosts from `alpha.11` advertise the optional `configure` capability. Behind it,
+the dashboard's organization owners and admins can manage goals, funnels,
+affiliates, site settings, and the retention policy of the granted sites without
+a host deploy. The scope is off unless the host opts in:
+
+- The control plane mints `rastro_permissions: ["analytics:read"]` for every
+  member and adds `"analytics:configure"` only for members whose organization
+  role is `owner` or `admin`.
+- The host's local grant lists the permissions it honors. A grant without
+  `permissions`, or without `analytics:configure` in it, is read only whatever
+  the token claims.
+- A configure function runs only when both agree; otherwise it fails with
+  `FEDERATION_CONFIGURE_FORBIDDEN` before the site scope is examined, so a
+  read-only token learns nothing about the grant by probing. `connectionStatus`
+  reports the effective permissions, and the dashboard renders forms only when
+  they include the configure scope; otherwise every form ends in the code the
+  host runs itself.
+
+The scope is bounded to configuration: `upsertGoal`, `removeGoal`,
+`upsertFunnel`, `removeFunnel`, `upsertAffiliate`, and `removeAffiliate` mirror
+the `Rastro` class, `listGoals`, `listFunnels`, and `listAffiliates` return the
+definitions, `setRetentionPolicy` and `disableRetentionPolicy` manage the
+recurring cleanup that `retentionStatus` reports, and `updateSite` changes only
+`name`, `domains`, and `timezone` — the currency is fixed by the ledger and
+`cookieless`, `networkId`, and `ownerId` stay outside the protocol.
+`siteSettings` is the one place the surface shows a site's `domains`, because a
+connection allowed to change them must see them; `listSites` stays redacted for
+every reader. Nothing in the scope ingests telemetry or enumerates sites beyond
+the grant. The constants `FEDERATED_ANALYTICS_CONFIGURE_PERMISSION`,
+`FEDERATED_ANALYTICS_PERMISSIONS`, `FEDERATED_ANALYTICS_CONFIGURE_FUNCTIONS`,
+the `federatedAnalyticsPermissionValidator`, and `effectiveFederatedPermissions`
+are exported for hosts and connector clients.
+
+## Authentication contract
+
+The customer host must configure Convex authentication to trust the Amage Rastro
+OIDC issuer. Convex validates the JWT signature, issuer, audience, and expiry
+before any host function runs. The helper then requires these custom claims:
+
+| Claim                    | Value                                                                      |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `rastro_connection_id`   | The paired deployment connection                                           |
+| `rastro_organization_id` | The Amage Rastro organization                                              |
+| `rastro_permissions`     | Must include `analytics:read`; owners and admins add `analytics:configure` |
+
+Claim names and the permission constants are exported as
+`FEDERATED_ANALYTICS_CLAIMS`, `FEDERATED_ANALYTICS_READ_PERMISSION`, and
+`FEDERATED_ANALYTICS_CONFIGURE_PERMISSION`.
+
+The audience is the customer's normalized Convex deployment URL, for example
+`https://product-123.convex.cloud`. It is stable across connections to that
+deployment; `rastro_connection_id` identifies the individual grant. A customer
+host configures the provider with the issuer and audience issued during pairing:
+
+```ts
+// convex/auth.config.ts
+import type { AuthConfig } from "convex/server";
+
+export default {
+  providers: [
+    // Keep the application's existing providers here.
+    {
+      domain: process.env.RASTRO_FEDERATION_ISSUER!,
+      applicationID: process.env.RASTRO_FEDERATION_AUDIENCE!,
+    },
+  ],
+} satisfies AuthConfig;
+```
+
+`RASTRO_FEDERATION_AUDIENCE` must exactly match the deployment URL registered in
+the control plane. Insert the provider object into the host's existing
+`providers` array; the complete insertion fragment is in
+[`federation-setup.md`](federation-setup.md). Never replace existing providers.
+The example control plane publishes OIDC discovery and JWKS endpoints under
+`/federation`, signs RS256 tokens with a ten-minute lifetime, and never sends
+its private key to the browser.
+
+## Authoritative local connection
+
+JWT claims identify a requested connection but do not define its site access.
+The customer deployment resolves a local connection record on every
+authenticated query. This record is authoritative and makes revocation immediate
+instead of waiting for a token to expire.
+
+A host schema can model it as:
+
+```ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  rastroFederationGrants: defineTable({
+    connectionId: v.string(),
+    organizationId: v.string(),
+    siteIds: v.array(v.string()),
+    // Absent means read only; ["analytics:configure"] opts into the scope.
+    permissions: v.optional(v.array(v.string())),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+    revokedAt: v.optional(v.number()),
+  }).index("by_connectionId", ["connectionId"]),
+});
+```
+
+Pairing and revocation mutations belong to the host application and must use its
+existing administrator authorization. The Rastro component cannot inspect host
+authentication state. The grant's `permissions`, like its `siteIds`, are the
+host's decision: a token cannot grant itself the configure scope.
+
+## Host API
+
+```ts
+// convex/rastroFederation.ts
+import {
+  exposeFederatedAnalyticsApi,
+  type FederatedAnalyticsConnection,
+  type FederatedAnalyticsPermission,
+} from "@iann29/rastro";
+import { components } from "./_generated/api";
+import { env, type QueryCtx } from "./_generated/server";
+
+// RASTRO_FEDERATION_ISSUER is declared optional in convex.config.ts so a push
+// never depends on it; the production issuer is the default.
+const issuer = (
+  env.RASTRO_FEDERATION_ISSUER ?? "https://site.api.amagerastro.com/federation"
+).replace(/\/$/, "");
+
+const federated = exposeFederatedAnalyticsApi(components.rastroAnalytics, {
+  issuer,
+  resolveConnection: async (ctx, identity) => {
+    const db = ctx.db as unknown as QueryCtx["db"];
+    const grant = await db
+      .query("rastroFederationGrants")
+      .withIndex("by_connectionId", (query) =>
+        query.eq("connectionId", identity.connectionId),
+      )
+      .unique();
+
+    if (!grant || grant.organizationId !== identity.organizationId) return null;
+    return {
+      connectionId: grant.connectionId,
+      organizationId: grant.organizationId,
+      siteIds: grant.siteIds,
+      permissions: grant.permissions as FederatedAnalyticsPermission[],
+      revokedAt: grant.revokedAt,
+    } satisfies FederatedAnalyticsConnection;
+  },
+});
+
+export const {
+  manifest,
+  connectionStatus,
+  listSites,
+  overview,
+  liveVisitors,
+  listSessions,
+  sessionJourney,
+  listConversions,
+  visitorJourney,
+  goalsReport,
+  funnelsReport,
+  affiliatesReport,
+  vitalsReport,
+  siteMap,
+  dataCoverage,
+  siteSettings,
+  updateSite,
+  listGoals,
+  upsertGoal,
+  removeGoal,
+  listFunnels,
+  upsertFunnel,
+  removeFunnel,
+  listAffiliates,
+  upsertAffiliate,
+  removeAffiliate,
+  retentionStatus,
+  setRetentionPolicy,
+  disableRetentionPolicy,
+} = federated;
+```
+
+The resolver receives the authenticated `UserIdentity` as well as the parsed
+connection and organization IDs, so a host may enforce additional local rules.
+It must use an indexed, authoritative host lookup rather than token-provided
+site IDs. A host that never lists `analytics:configure` in a grant may leave the
+configure functions out of the export; the manifest still advertises them, and
+the dashboard never calls them for a read-only connection.
+
+## Stable errors
+
+`FEDERATED_ANALYTICS_ERROR_CODES` exports all protocol v1 authorization codes:
+
+| Code                             | Meaning                                      |
+| -------------------------------- | -------------------------------------------- |
+| `FEDERATION_UNAUTHENTICATED`     | No authenticated identity                    |
+| `FEDERATION_ISSUER_MISMATCH`     | Identity came from another issuer            |
+| `FEDERATION_INVALID_CLAIMS`      | Required bounded claims or permission absent |
+| `FEDERATION_CONNECTION_DENIED`   | Connection missing, revoked, or malformed    |
+| `FEDERATION_INVALID_SCOPE`       | Requested site list violates public limits   |
+| `FEDERATION_SITE_DENIED`         | Requested site is outside the connection     |
+| `FEDERATION_CONFIGURE_FORBIDDEN` | Token or grant lacks `analytics:configure`   |
+
+Consumers should branch on `ConvexError.data.code`, not human-readable messages.
+
+## Enforced invariants
+
+- The identity issuer must match exactly.
+- The token must include the read permission.
+- A configure function runs only when the token and the grant both carry
+  `analytics:configure`; a grant listing an unknown permission is denied whole.
+- Report queries must request one through ten unique, bounded site IDs.
+- The resolved connection ID and organization must match the token.
+- Revoked, missing, malformed, empty, or duplicate-site connections are denied.
+- The resolved connection may authorize at most 10 unique site IDs.
+- Every report site must exist in the local connection scope.
+- Site discovery trusts only the resolved connection, never caller arguments.
+- Owner-wide enumeration, ingestion, and arbitrary host functions are absent;
+  the only writes are the configure scope's, and `listSites` never returns
+  `ownerId`, `domains`, or `networkId`.
+- `dataCoverage` is read-only and uses the same connection-scoped site
+  authorization.
+
+`dataCoverage` accepts one authorized `siteId` and an inclusive integer
+millisecond `from`/`to` range. It returns availability, rollup generation, and
+retention boundaries for each dashboard dataset, but no events, visitor IDs,
+session IDs, or site configuration. Dashboard clients should use it to explain
+`complete`, `partial`, `retained`, and `unavailable` states rather than treating
+an empty report as proof that no telemetry exists.
+
+Availability is derived from bounded indexed source reads rather than a shared
+per-ingest watermark. The dataset list distinguishes `overviewHour` from
+`overviewDay`; clients must not apply one granularity's retention boundary to
+the other. Heartbeats advance `sessions` availability only, not `events` or
+either overview dataset.
+
+## Control-plane status
+
+The production control plane at `https://www.amagerastro.com` and its reference
+implementation under `control-plane/` provide Better Auth sessions,
+organization-scoped connections, OIDC discovery, JWKS, ten-minute RS256 tokens
+whose permissions follow the member's organization role, manifest verification,
+redacted site discovery, audit records, revocation of new token issuance, and
+dynamic browser subscriptions to active deployments. Verification records the
+permissions the host honors for an admin token, so **Conexões** shows whether a
+connection is read only or reads and configures.
+
+Do not assume that a dist-tag or source checkout contains this protocol. Inspect
+an operator-approved exact npm registry artifact outside the host, without
+lifecycle scripts, and statically verify every runtime and declaration export
+listed by the machine manifest before changing a customer deployment. Automation
+must stop at this gate rather than fetching source or reimplementing the
+connector.
+
+Remote local-grant provisioning is intentionally not an unauthenticated control-
+plane write. The customer operator provisions the authoritative grant through an
+internal or host-admin mutation. For immediate revocation, revoke that local
+grant before revoking the central connection; otherwise an already-issued token
+remains valid until its ten-minute expiry.