@iann29/rastro 0.1.0-alpha.9 → 0.1.0

package/agent/integration.md

@@ -17,11 +17,15 @@ not which mutable tag currently contains them.
 Inspect the tag without changing the host:
 
 ```bash
-npm view @iann29/rastro@alpha version
+npm view @iann29/rastro version
 ```
 
 After the operator approves that exact version, inspect it outside the host
-without executing package code or lifecycle scripts:
+without executing package code or lifecycle scripts. Run the block from a
+directory whose `node_modules` resolves `typescript` — the host checkout after
+`npm install` is the natural place. From anywhere else the inspector exits with
+`ERR_MODULE_NOT_FOUND` for `typescript` and `npx --no-install tsc` finds no
+compiler; neither outcome is a verdict about the package.
 
 ```bash
 tmp="$(mktemp -d)"; trap 'rm -rf "$tmp"' EXIT
@@ -244,7 +248,7 @@ repository commit.
 ```text
 product browser -> customer HTTP-actions URL -> customer Rastro tables
 
-amagerastro.com browser -> customer functions URL -> read-only reports
+amagerastro.com browser -> customer functions URL -> reports (+ opt-in configure)
                               ^
                               |
                  short-lived control-plane JWT
@@ -316,7 +320,11 @@ Confirm local analytics first:
 2. The site exists and its domains include the exact product hostname.
 3. The tracker loads from `<HTTP_ACTIONS_URL>/rastro/tracker.js`.
 4. A real `POST /rastro/events` returns HTTP 200 with accepted counters.
-5. An authenticated host query can read a report for that exact site.
+5. An authenticated host query can read a report for that exact site. Check with
+   `liveVisitors` or `sessionJourney`, which reflect an accepted request
+   immediately; `listSessions` and the bucketed `overview` can trail it by
+   seconds, so an empty result from those two right after the request is not a
+   failed ingestion.
 6. Retained routes, IDs, campaigns, affiliates, location fields, conversion
    records, and custom properties contain no unexpected personal data, access
    tokens, secrets, or form values. Confirm that every intended organization
@@ -347,6 +355,7 @@ rastroFederationGrants: defineTable({
   connectionId: v.string(),
   organizationId: v.string(),
   siteIds: v.array(v.string()),
+  permissions: v.optional(v.array(v.string())),
   revokedAt: v.optional(v.number()),
   createdAt: v.number(),
   updatedAt: v.number(),
@@ -356,7 +365,12 @@ rastroFederationGrants: defineTable({
 Create `convex/rastroFederationAdmin.ts` with internal or equivalently protected
 operator functions that:
 
-- accept a connection ID, organization ID, opaque host owner ID, and site IDs;
+- accept a connection ID, organization ID, opaque host owner ID, site IDs, and
+  an optional `permissions` list validated with
+  `federatedAnalyticsPermissionValidator` (absent means read only;
+  `"analytics:configure"` opts the connection into the configure scope, and
+  `"analytics:public"` lets the dashboard publish read-only public links of the
+  granted sites);
 - reject empty/duplicate IDs and more than ten unique sites;
 - load every site from Rastro and verify it belongs to that owner;
 - upsert by the `by_connectionId` index and clear `revokedAt` when
@@ -376,10 +390,16 @@ object. If the app has no `env` object, add one without changing any other
 `defineApp` option. Do not add another Rastro mount:
 
 ```ts
-RASTRO_FEDERATION_ISSUER: v.string(),
-RASTRO_FEDERATION_AUDIENCE: v.string(),
+RASTRO_FEDERATION_ISSUER: v.optional(v.string()),
+RASTRO_FEDERATION_AUDIENCE: v.optional(v.string()),
 ```
 
+Declare them optional. A required `v.string()` makes the push fail on every
+deployment where the values are not set yet, which is every deployment that
+pushes code before pairing. Set both values before pushing: `auth.config.ts`
+reads them at deploy time, so values set after a push take effect only on the
+next push.
+
 Insert this conditional spread into the existing `providers` array; never
 replace the array or its current entries:
 
@@ -432,12 +452,21 @@ name `rastroFederation`.
 import {
   exposeFederatedAnalyticsApi,
   type FederatedAnalyticsConnection,
+  type FederatedAnalyticsPermission,
 } from "@iann29/rastro";
 import { components } from "./_generated/api";
 import { env, type QueryCtx } from "./_generated/server";
 
+/** The production Amage Rastro OIDC issuer; override with RASTRO_FEDERATION_ISSUER. */
+export const DEFAULT_FEDERATION_ISSUER =
+  "https://site.api.amagerastro.com/federation";
+
+export const federationIssuer = (
+  env.RASTRO_FEDERATION_ISSUER ?? DEFAULT_FEDERATION_ISSUER
+).replace(/\/$/, "");
+
 const federated = exposeFederatedAnalyticsApi(components.rastroAnalytics, {
-  issuer: env.RASTRO_FEDERATION_ISSUER.replace(/\/$/, ""),
+  issuer: federationIssuer,
   resolveConnection: async (ctx, identity) => {
     const db = ctx.db as unknown as QueryCtx["db"];
     const grant = await db
@@ -452,6 +481,7 @@ const federated = exposeFederatedAnalyticsApi(components.rastroAnalytics, {
       connectionId: grant.connectionId,
       organizationId: grant.organizationId,
       siteIds: grant.siteIds,
+      permissions: grant.permissions as FederatedAnalyticsPermission[],
       revokedAt: grant.revokedAt,
     } satisfies FederatedAnalyticsConnection;
   },
@@ -473,39 +503,94 @@ export const {
   vitalsReport,
   siteMap,
   dataCoverage,
+  siteSettings,
+  updateSite,
+  listGoals,
+  upsertGoal,
+  removeGoal,
+  listFunnels,
+  upsertFunnel,
+  removeFunnel,
+  listAffiliates,
+  upsertAffiliate,
+  removeAffiliate,
+  retentionStatus,
+  setRetentionPolicy,
+  disableRetentionPolicy,
 } = federated;
 ```
 
-`manifest` is public static metadata. Every other function is read-only and
-requires both a valid JWT and a matching, non-revoked local grant.
+`manifest` is public static metadata. Every report function is read-only and
+requires both a valid JWT and a matching, non-revoked local grant. The functions
+from `siteSettings` down form the configure scope (optional capability
+`configure`, hosts from `alpha.11`): they additionally require
+`analytics:configure` on the token — the control plane claims it only for
+organization owners and admins — and in the grant's `permissions`, and fail with
+`FEDERATION_CONFIGURE_FORBIDDEN` otherwise. Export them even when every grant
+stays read only, so a later opt-in needs no host deploy; the dashboard never
+calls them for a read-only connection. The issuer falls back to the production
+control plane so the module compiles and pushes before the environment variable
+exists; tokens are still rejected until `auth.config.ts` trusts the same issuer,
+which needs both variables set and a push afterwards.
+
+A public link's token carries `analytics:public` instead of `analytics:read` and
+`rastro_site_ids` naming the link's sites. It runs only `manifest`,
+`connectionStatus`, `listSites`, `overview` (with zero revenue and conversions
+and empty campaigns, mediums, events, and goals), `liveVisitors` (with
+`visitorId` replaced by the session id and without the entry path, return,
+campaign, affiliate, conversion, and funnel fields), and `dataCoverage`;
+everything else fails with `FEDERATION_PUBLIC_FORBIDDEN`, and so does every call
+while the grant does not list `analytics:public`. A host from before the
+permission rejects the token with `FEDERATION_INVALID_CLAIMS`.
 
 ## Function contract
 
-| Function           | Input summary                                           | Important output/behavior                                        |
-| ------------------ | ------------------------------------------------------- | ---------------------------------------------------------------- |
-| `manifest`         | `{}`                                                    | Static protocol, capabilities, names, and limits; no auth        |
-| `connectionStatus` | `{}`                                                    | Redacted status, protocol version, capabilities, site count      |
-| `listSites`        | `{}`                                                    | Only `siteId`, `name`, `currency`, `timezone`, `cookieless`      |
-| `overview`         | `siteIds`, `from`, `to`, optional hour/day interval     | Aggregate metrics and time series                                |
-| `liveVisitors`     | `siteIds`, `now`, optional limit                        | At most 500 visitors seen in the last five minutes               |
-| `listSessions`     | one `siteId`, range, `{numItems,cursor}` keyset options | Paginated sessions                                               |
-| `sessionJourney`   | one site/session, range, `{numItems,cursor}` options    | Paginated bounded events                                         |
-| `listConversions`  | one site, range, `{numItems,cursor}` options            | Paginated trusted server-side conversion ledger                  |
-| `visitorJourney`   | site IDs, visitor ID, range, optional limit             | Cross-site journey inside the grant only                         |
-| `goalsReport`      | one site and range                                      | Read-only goal definitions plus aggregates                       |
-| `funnelsReport`    | one site and complete UTC-day range                     | Read-only definitions/steps plus aggregates; max 90 days         |
-| `affiliatesReport` | one site and complete UTC-day range                     | Read-only affiliate definitions plus aggregates                  |
-| `vitalsReport`     | one site and complete UTC-day range                     | Web Vitals p75/ratings per metric, page, and device; max 90 days |
-| `siteMap`          | site IDs and complete UTC-day range                     | Routes with derived exits/bounces plus transitions; max 90 days  |
-| `dataCoverage`     | one site and inclusive integer range                    | Coverage metadata; echoes site ID, no event/visitor/session IDs  |
-
-The federated surface deliberately excludes ingestion, site mutation, retention
-writes, configuration writes, domains, owner IDs, network IDs, and arbitrary
-host functions. Goal, funnel, and affiliate reports include their read-only
-definitions. Journey events include bounded custom `properties`; hosts must
-follow the tracker contract and never place personal data or secrets in them. A
-session belongs to one site; only `visitorJourney` can join the same
-pseudonymous visitor across explicitly granted sites.
+| Function           | Input summary                                           | Important output/behavior                                             |
+| ------------------ | ------------------------------------------------------- | --------------------------------------------------------------------- |
+| `manifest`         | `{}`                                                    | Static protocol, capabilities, names, and limits; no auth             |
+| `connectionStatus` | `{}`                                                    | Redacted status, protocol version, capabilities, site count           |
+| `listSites`        | `{}`                                                    | Only `siteId`, `name`, `currency`, `timezone`, `cookieless`           |
+| `overview`         | `siteIds`, `from`, `to`, optional hour/day interval     | Aggregate metrics and time series                                     |
+| `liveVisitors`     | `siteIds`, `now`, optional limit                        | At most 500 visitors seen in the last five minutes, with intent facts |
+| `listSessions`     | one `siteId`, range, `{numItems,cursor}` keyset options | Paginated sessions                                                    |
+| `sessionJourney`   | one site/session, range, `{numItems,cursor}` options    | Paginated bounded events                                              |
+| `listConversions`  | one site, range, `{numItems,cursor}` options            | Paginated trusted server-side conversion ledger                       |
+| `visitorJourney`   | site IDs, visitor ID, range, optional limit             | Cross-site journey inside the grant only                              |
+| `goalsReport`      | one site and range                                      | Read-only goal definitions plus aggregates                            |
+| `funnelsReport`    | one site and complete UTC-day range                     | Read-only definitions/steps plus aggregates; max 90 days              |
+| `affiliatesReport` | one site and complete UTC-day range                     | Read-only affiliate definitions plus aggregates                       |
+| `vitalsReport`     | one site and complete UTC-day range                     | Web Vitals p75/ratings per metric, page, and device; max 90 days      |
+| `siteMap`          | site IDs and complete UTC-day range                     | Routes with derived exits/bounces plus transitions; max 90 days       |
+| `dataCoverage`     | one site and inclusive integer range                    | Coverage metadata; echoes site ID, no event/visitor/session IDs       |
+
+The configure scope, every function of which requires `analytics:configure` on
+the token and in the grant:
+
+| Function                 | Input summary                                                | Important output/behavior                                           |
+| ------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `siteSettings`           | one `siteId`                                                 | `name`, `domains`, `timezone`, `currency`, `cookieless`; no owner   |
+| `updateSite`             | one `siteId`, optional `name`, `domains`, `timezone`         | Changes only those three; currency and `cookieless` stay outside    |
+| `listGoals`              | one `siteId`                                                 | Goal definitions, at most 50                                        |
+| `upsertGoal`             | `siteId`, optional `goalId`, key, name, matcher, value, flag | Returns the goal ID; keys and active matchers are unique per site   |
+| `removeGoal`             | `siteId`, `goalId`                                           | Deletes the definition; rollups already written remain              |
+| `listFunnels`            | one `siteId`                                                 | Funnel definitions, at most 20                                      |
+| `upsertFunnel`           | `siteId`, optional `funnelId`, key, name, 2–10 steps, window | Returns the funnel ID; window between one minute and 90 days        |
+| `removeFunnel`           | `siteId`, `funnelId`                                         | Deletes the definition                                              |
+| `listAffiliates`         | one `siteId`                                                 | Affiliate definitions, at most 100                                  |
+| `upsertAffiliate`        | `siteId`, optional `affiliateId`, slug, name, bps, window    | Returns the affiliate ID; commission 0–10000 bps, window 1–365 days |
+| `removeAffiliate`        | `siteId`, `affiliateId`                                      | Deletes the definition; accounted commissions remain                |
+| `retentionStatus`        | one `siteId`                                                 | The policy, its cleanup jobs, and the backlog                       |
+| `setRetentionPolicy`     | `siteId` and five day counts between 1 and 3650              | Starts the recurring cleanup chains                                 |
+| `disableRetentionPolicy` | one `siteId`                                                 | Stops automatic cleanup; nothing is restored                        |
+
+The federated surface deliberately excludes ingestion, owner IDs, network IDs,
+and arbitrary host functions, and shows a site's domains only through
+`siteSettings` to a connection allowed to change them. Goal, funnel, and
+affiliate reports include their read-only definitions. Journey events include
+bounded custom `properties`; hosts must follow the tracker contract and never
+place personal data or secrets in them. A session belongs to one site; only
+`visitorJourney` can join the same pseudonymous visitor across explicitly
+granted sites.
 
 All times are Unix epoch milliseconds. The global report ceiling is 366 days,
 but hourly overview is limited to 24 hours and funnel reports to 90 complete UTC
@@ -552,14 +637,21 @@ synapse convex --dev run rastroFederationAdmin:provisionConnection \
 ```
 
 Never copy site IDs from JWT claims or grant every site belonging to an owner.
-The operator must name one through ten exact site IDs.
+The operator must name one through ten exact site IDs. Add
+`"permissions":["analytics:configure"]` to the same JSON only when the operator
+wants the dashboard's owners and admins to configure those sites; omit it for a
+read-only connection, and rerun without it to revoke the scope.
 
 ## Phase 6: verify in order
 
 Do not mark integration complete until all checks pass:
 
 1. Call `rastroFederation:manifest` without auth and deep-compare its connector
-   fields with <https://www.amagerastro.com/agent/manifest.json>.
+   fields with the `connector` object of
+   <https://www.amagerastro.com/agent/manifest.json>. Compare structurally
+   (`assert.deepStrictEqual`, `toEqual`, or an equivalent order-insensitive
+   check), never as serialized text: the served object and the JSON file list
+   the same keys in a different order.
 2. In **Conexões**, click **Verificar conexão** and confirm active status and
    the exact site count.
 3. Confirm `listSites` omits domains, owner IDs, network IDs, connection IDs,
@@ -583,41 +675,106 @@ Do not mark integration complete until all checks pass:
     report, and require `FEDERATION_CONNECTION_DENIED` before central
     revocation.
 11. Reprovision only if the rehearsal requires restoring the development grant.
+12. In the same suite, call `upsertGoal` with a read-only identity and require
+    `FEDERATION_CONFIGURE_FORBIDDEN`; when the grant lists
+    `analytics:configure`, call it with an identity whose `rastro_permissions`
+    includes `analytics:configure` and require the goal in `listGoals`, then
+    require `FEDERATION_SITE_DENIED` for a site outside the grant.
+13. In the same suite, call `listSessions` with an identity whose
+    `rastro_permissions` is `["analytics:public"]` and require
+    `FEDERATION_PUBLIC_FORBIDDEN`; when the grant lists `analytics:public`,
+    require `overview` to answer that identity with zero `revenueCents` and an
+    empty `topGoals`.
+
+Use this harness when the host has no `convex-test` suite yet. Convex functions
+run under `edge-runtime` in tests, which is what a deployed function gets, so
+install `vitest`, `convex-test`, and `@edge-runtime/vm` as dev dependencies and
+configure the environment and the issuer the identity will claim:
 
-Use this assertion shape in the host's existing `convex-test` harness after
-registering its schema, modules, component, and `api.rastroFederation`:
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "edge-runtime",
+    env: {
+      RASTRO_FEDERATION_ISSUER: "https://site.api.amagerastro.com/federation",
+    },
+  },
+});
+```
+
+Register the host schema and modules together with the Rastro component; the
+package's `test` entry registers it under the mounted name `rastroAnalytics`:
 
 ```ts
-const identity = {
-  issuer: RASTRO_FEDERATION_ISSUER,
-  subject: "rastro-negative-test",
-  tokenIdentifier: `${RASTRO_FEDERATION_ISSUER}|rastro-negative-test`,
-  rastro_connection_id: CONNECTION_ID,
-  rastro_organization_id: ORGANIZATION_ID,
-  rastro_permissions: ["analytics:read"],
-};
-
-await expect(
-  t.query(api.rastroFederation.overview, allowedArgs),
-).rejects.toMatchObject({ data: { code: "FEDERATION_UNAUTHENTICATED" } });
-await expect(
-  t.withIdentity(identity).query(api.rastroFederation.overview, {
-    ...allowedArgs,
-    siteIds: [KNOWN_OUTSIDE_GRANT_SITE_ID],
-  }),
-).rejects.toMatchObject({ data: { code: "FEDERATION_SITE_DENIED" } });
+// convex/setup.test.ts
+/// <reference types="vite/client" />
+import { convexTest } from "convex-test";
+import component from "@iann29/rastro/test";
+import schema from "./schema";
+
+const modules = import.meta.glob("./**/*.*s");
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules);
+  component.register(t);
+  return t;
+}
 ```
 
+Then use this assertion shape, with `federationIssuer` imported from
+`convex/rastroFederation.ts` so the identity claims the issuer the module
+verifies:
+
+```ts
+// convex/rastroFederation.test.ts
+import { expect, test } from "vitest";
+import { api } from "./_generated/api";
+import { federationIssuer } from "./rastroFederation";
+import { initConvexTest } from "./setup.test";
+
+test("denies a site outside the grant", async () => {
+  const t = initConvexTest();
+  const identity = {
+    issuer: federationIssuer,
+    subject: "rastro-negative-test",
+    tokenIdentifier: `${federationIssuer}|rastro-negative-test`,
+    rastro_connection_id: CONNECTION_ID,
+    rastro_organization_id: ORGANIZATION_ID,
+    rastro_permissions: ["analytics:read"],
+  };
+
+  await expect(
+    t.query(api.rastroFederation.overview, allowedArgs),
+  ).rejects.toMatchObject({ data: { code: "FEDERATION_UNAUTHENTICATED" } });
+  await expect(
+    t.withIdentity(identity).query(api.rastroFederation.overview, {
+      ...allowedArgs,
+      siteIds: [KNOWN_OUTSIDE_GRANT_SITE_ID],
+    }),
+  ).rejects.toMatchObject({ data: { code: "FEDERATION_SITE_DENIED" } });
+});
+```
+
+Provision the grant for `CONNECTION_ID` inside the test with
+`t.mutation(internal.rastroFederationAdmin.provisionConnection, ...)` after
+creating a site through the host's own admin function; `allowedArgs` names that
+site and a complete UTC-day range.
+
 Consumers must branch on `ConvexError.data.code`, not human-readable text:
 
-| Code                           | Meaning                                                           |
-| ------------------------------ | ----------------------------------------------------------------- |
-| `FEDERATION_UNAUTHENTICATED`   | No authenticated Rastro identity                                  |
-| `FEDERATION_ISSUER_MISMATCH`   | Identity came from another issuer                                 |
-| `FEDERATION_INVALID_CLAIMS`    | Required bounded claims or permission are absent                  |
-| `FEDERATION_CONNECTION_DENIED` | Local grant is missing, malformed, mismatched, or revoked         |
-| `FEDERATION_INVALID_SCOPE`     | Requested site list is empty, duplicate, malformed, or over limit |
-| `FEDERATION_SITE_DENIED`       | A requested site is outside the local grant                       |
+| Code                             | Meaning                                                                        |
+| -------------------------------- | ------------------------------------------------------------------------------ |
+| `FEDERATION_UNAUTHENTICATED`     | No authenticated Rastro identity                                               |
+| `FEDERATION_ISSUER_MISMATCH`     | Identity came from another issuer                                              |
+| `FEDERATION_INVALID_CLAIMS`      | Required bounded claims or permission are absent                               |
+| `FEDERATION_CONNECTION_DENIED`   | Local grant is missing, malformed, mismatched, or revoked                      |
+| `FEDERATION_INVALID_SCOPE`       | Requested site list is empty, duplicate, malformed, or over limit              |
+| `FEDERATION_SITE_DENIED`         | A requested site is outside the local grant                                    |
+| `FEDERATION_CONFIGURE_FORBIDDEN` | The token or the grant lacks `analytics:configure`                             |
+| `FEDERATION_PUBLIC_FORBIDDEN`    | A public token asked beyond its surface, or the grant lacks `analytics:public` |
 
 ## Revocation
 
@@ -649,6 +806,7 @@ Package/version: <exact eligible registry version>
 Existing auth providers preserved: yes/no
 Manifest protocol: <value>
 Granted site count: <1..10>
+Configure scope granted: yes/no
 Ingestion verified: yes/no
 Authorized reports verified: yes/no
 Wrong-site denial verified: yes/no

package/agent/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://www.amagerastro.com/agent/manifest.schema.json",
   "name": "amage-rastro",
   "title": "Amage Rastro",
-  "description": "Privacy-first, real-time web analytics for Convex with a read-only federated dashboard.",
+  "description": "Privacy-first, real-time web analytics for Convex with a federated dashboard that reads every granted site and configures only those whose host opts in.",
   "manifestVersion": "1.0.0",
   "language": "en",
   "canonicalBaseUrl": "https://www.amagerastro.com",
@@ -15,11 +15,11 @@
     "upgrading": "https://www.amagerastro.com/docs/reference/upgrading.md",
     "integrity": {
       "algorithm": "sha256",
-      "agent": "b641b6cdecc0c23291e169bceef6308d1679392bec0b5c9e11715b6740be83b3",
-      "llms": "0dab84ee468ef3f22c7560bd0080957218f66d3014a660be0e93bbef1de0ccd5",
-      "protocol": "57fe1d40b81a872a027294945dc577b4a6346562620f2772074dc534c11c9190",
-      "setup": "5e7cd04a7b285a887404fe3cdae918a63374822e656395df2b50f57736e0fd54",
-      "upgrading": "7679c82a8353549687cfda2b09a858d4fe0fe41f172366084d05f95d755e0626"
+      "agent": "36afaee7c37f8ccf8b17e2b8c9fcb35de137745f59b9e387b1e7d89d6c70a524",
+      "llms": "08e9581c9ee626642753db971e9c4da22d131ddb62870cca402d2e93ce4f7567",
+      "protocol": "a297bf4dc610b3f0658fa131a2dc9a61b04a3bffe49320e27a58f0abe1ae716e",
+      "setup": "f0777e3ce5785ab1d6c9e13dae0ef3c3ca59f1c1d84bbeb7e61f8b909f236d16",
+      "upgrading": "8f37826ce035431103ffe3fe47f7f302b134886be5f4c4252a60e536d6f6cce7"
     }
   },
   "controlPlane": {
@@ -34,7 +34,7 @@
   },
   "package": {
     "name": "@iann29/rastro",
-    "distTag": "alpha",
+    "distTag": "latest",
     "availability": "verify-exact-registry-artifact",
     "requiredRuntimeExports": [
       "exposeFederatedAnalyticsApi",
@@ -46,7 +46,7 @@
       "FederatedAnalyticsAuthorizerOptions",
       "FederatedSiteSummary"
     ],
-    "versionDiscoveryCommand": "npm view @iann29/rastro@alpha version",
+    "versionDiscoveryCommand": "npm view @iann29/rastro version",
     "inspectionPolicy": "static-tarball-inspection-no-lifecycle-scripts",
     "agentActionWhenUnavailable": "stop-and-request-eligible-release"
   },
@@ -69,7 +69,21 @@
       "affiliatesReport": "affiliatesReport",
       "dataCoverage": "dataCoverage",
       "vitalsReport": "vitalsReport",
-      "siteMap": "siteMap"
+      "siteMap": "siteMap",
+      "siteSettings": "siteSettings",
+      "updateSite": "updateSite",
+      "listGoals": "listGoals",
+      "upsertGoal": "upsertGoal",
+      "removeGoal": "removeGoal",
+      "listFunnels": "listFunnels",
+      "upsertFunnel": "upsertFunnel",
+      "removeFunnel": "removeFunnel",
+      "listAffiliates": "listAffiliates",
+      "upsertAffiliate": "upsertAffiliate",
+      "removeAffiliate": "removeAffiliate",
+      "retentionStatus": "retentionStatus",
+      "setRetentionPolicy": "setRetentionPolicy",
+      "disableRetentionPolicy": "disableRetentionPolicy"
     },
     "capabilities": [
       "siteSummaries",
@@ -84,7 +98,9 @@
       "affiliates",
       "dataCoverage",
       "vitals",
-      "siteMap"
+      "siteMap",
+      "localDays",
+      "configure"
     ],
     "limits": {
       "maxSitesPerRequest": 10,
@@ -98,10 +114,13 @@
     "providerType": "customJwt",
     "audience": "exact-normalized-customer-functions-url",
     "permission": "analytics:read",
+    "configurePermission": "analytics:configure",
+    "publicPermission": "analytics:public",
     "claims": {
       "connectionId": "rastro_connection_id",
       "organizationId": "rastro_organization_id",
-      "permissions": "rastro_permissions"
+      "permissions": "rastro_permissions",
+      "siteIds": "rastro_site_ids"
     },
     "authoritativeScope": "customer-deployment-local-grant"
   },
@@ -160,7 +179,7 @@
     "Never accept ownerId, userId, organizationId, or site scope from an untrusted client as authorization.",
     "Never replace existing authentication providers; append the Rastro provider.",
     "Never use JWT site IDs as authoritative scope; resolve the indexed local grant on every query.",
-    "Never expose writes, raw site configuration, owner-wide enumeration, or ingestion through the federated module.",
+    "Never expose ingestion, owner-wide enumeration, or arbitrary host functions through the federated module; configuration writes run only when both the token and the local grant carry analytics:configure.",
     "Never run a deployment-affecting command without an explicit development or production target.",
     "Revoke the local grant before central revocation when immediate denial is required.",
     "Keep telemetry in the customer deployment."
@@ -182,6 +201,8 @@
     "FEDERATION_INVALID_CLAIMS",
     "FEDERATION_CONNECTION_DENIED",
     "FEDERATION_INVALID_SCOPE",
-    "FEDERATION_SITE_DENIED"
+    "FEDERATION_SITE_DENIED",
+    "FEDERATION_CONFIGURE_FORBIDDEN",
+    "FEDERATION_PUBLIC_FORBIDDEN"
   ]
 }

package/agent/manifest.schema.json

@@ -114,7 +114,7 @@
       ],
       "properties": {
         "name": { "const": "@iann29/rastro" },
-        "distTag": { "const": "alpha" },
+        "distTag": { "const": "latest" },
         "availability": { "const": "verify-exact-registry-artifact" },
         "requiredRuntimeExports": {
           "type": "array",
@@ -169,7 +169,21 @@
             "affiliatesReport",
             "dataCoverage",
             "vitalsReport",
-            "siteMap"
+            "siteMap",
+            "siteSettings",
+            "updateSite",
+            "listGoals",
+            "upsertGoal",
+            "removeGoal",
+            "listFunnels",
+            "upsertFunnel",
+            "removeFunnel",
+            "listAffiliates",
+            "upsertAffiliate",
+            "removeAffiliate",
+            "retentionStatus",
+            "setRetentionPolicy",
+            "disableRetentionPolicy"
           ],
           "properties": {
             "manifest": { "const": "manifest" },
@@ -186,14 +200,28 @@
             "affiliatesReport": { "const": "affiliatesReport" },
             "dataCoverage": { "const": "dataCoverage" },
             "vitalsReport": { "const": "vitalsReport" },
-            "siteMap": { "const": "siteMap" }
+            "siteMap": { "const": "siteMap" },
+            "siteSettings": { "const": "siteSettings" },
+            "updateSite": { "const": "updateSite" },
+            "listGoals": { "const": "listGoals" },
+            "upsertGoal": { "const": "upsertGoal" },
+            "removeGoal": { "const": "removeGoal" },
+            "listFunnels": { "const": "listFunnels" },
+            "upsertFunnel": { "const": "upsertFunnel" },
+            "removeFunnel": { "const": "removeFunnel" },
+            "listAffiliates": { "const": "listAffiliates" },
+            "upsertAffiliate": { "const": "upsertAffiliate" },
+            "removeAffiliate": { "const": "removeAffiliate" },
+            "retentionStatus": { "const": "retentionStatus" },
+            "setRetentionPolicy": { "const": "setRetentionPolicy" },
+            "disableRetentionPolicy": { "const": "disableRetentionPolicy" }
           },
           "additionalProperties": false
         },
         "capabilities": {
           "type": "array",
-          "minItems": 13,
-          "maxItems": 13,
+          "minItems": 15,
+          "maxItems": 15,
           "uniqueItems": true,
           "items": {
             "enum": [
@@ -209,7 +237,9 @@
               "affiliates",
               "dataCoverage",
               "vitals",
-              "siteMap"
+              "siteMap",
+              "localDays",
+              "configure"
             ]
           }
         },
@@ -240,6 +270,8 @@
         "providerType",
         "audience",
         "permission",
+        "configurePermission",
+        "publicPermission",
         "claims",
         "authoritativeScope"
       ],
@@ -247,13 +279,21 @@
         "providerType": { "const": "customJwt" },
         "audience": { "const": "exact-normalized-customer-functions-url" },
         "permission": { "const": "analytics:read" },
+        "configurePermission": { "const": "analytics:configure" },
+        "publicPermission": { "const": "analytics:public" },
         "claims": {
           "type": "object",
-          "required": ["connectionId", "organizationId", "permissions"],
+          "required": [
+            "connectionId",
+            "organizationId",
+            "permissions",
+            "siteIds"
+          ],
           "properties": {
             "connectionId": { "const": "rastro_connection_id" },
             "organizationId": { "const": "rastro_organization_id" },
-            "permissions": { "const": "rastro_permissions" }
+            "permissions": { "const": "rastro_permissions" },
+            "siteIds": { "const": "rastro_site_ids" }
           },
           "additionalProperties": false
         },
@@ -379,8 +419,8 @@
     },
     "stableErrors": {
       "type": "array",
-      "minItems": 6,
-      "maxItems": 6,
+      "minItems": 8,
+      "maxItems": 8,
       "uniqueItems": true,
       "items": {
         "enum": [
@@ -389,7 +429,9 @@
           "FEDERATION_INVALID_CLAIMS",
           "FEDERATION_CONNECTION_DENIED",
           "FEDERATION_INVALID_SCOPE",
-          "FEDERATION_SITE_DENIED"
+          "FEDERATION_SITE_DENIED",
+          "FEDERATION_CONFIGURE_FORBIDDEN",
+          "FEDERATION_PUBLIC_FORBIDDEN"
         ]
       }
     }