@iann29/rastro 0.1.0-alpha.2 → 0.1.0-alpha.4

package/docs/federation-setup.md

@@ -0,0 +1,395 @@
+# Federated dashboard setup
+
+This runbook connects an existing Convex or Synapse project to the Amage Rastro
+control plane without moving telemetry out of that project. Read
+[`federation.md`](federation.md) for the protocol and threat model.
+
+## Package eligibility requirement
+
+Do not infer federation availability from this website, a dist-tag, or a source
+checkout. Discover the current tag without changing the host:
+
+```bash
+npm view @iann29/rastro@alpha version
+```
+
+After the operator approves that exact version, execute the complete static
+tarball, export-map, AST, and TypeScript consumer probe in the **Package
+eligibility gate** of the canonical
+[`agent/integration.md`](https://www.amagerastro.com/agent/integration.md). Do
+not replace it with an `import()` test, which executes package code, or a text
+search, which can accept comments and broken re-exports.
+
+If verification fails, stop and request an eligible release. If it passes,
+record that exact version but do not install it yet. Detect the currently
+installed version with `npm ls @iann29/rastro --depth=0`, then follow
+[`upgrading.md`](upgrading.md): snapshot/rehearse maintained deployments and
+complete every required migration bridge. Only then install with
+`npm install --ignore-scripts --save-exact @iann29/rastro@EXACT_VERSION` and
+commit the lockfile. Never fetch a mutable branch or install a source tarball
+supplied by this website.
+
+## 1. Verify local analytics first
+
+Do not configure federation until the customer deployment already has:
+
+- the Rastro component mounted under `/rastro/`;
+- at least one site with the correct allowed browser domains;
+- a tracker using the deployment's HTTP-actions URL;
+- an accepted `POST /rastro/events` request;
+- a protected local report returning that site's telemetry.
+- an audit through authorized local reports of retained routes, visitor/session
+  IDs, live location, campaigns, affiliates, conversions, and custom properties,
+  proving that no unexpected personal data, credentials, secrets, or form values
+  will become visible to the intended dashboard organization members and that
+  retention is acceptable.
+
+The README quickstart covers those steps. Federation only exposes existing
+reports; it does not install the tracker or create sites.
+
+## 2. Record both deployment URLs
+
+The connection form requires two different base URLs with no path, query, hash,
+username, or password:
+
+| Field          | Used for                          | Convex Cloud example           | Synapse example                        |
+| -------------- | --------------------------------- | ------------------------------ | -------------------------------------- |
+| URL de funções | Reactive queries and JWT audience | `https://product.convex.cloud` | `https://product.synapse.example`      |
+| URL HTTP       | Tracker and event ingestion       | `https://product.convex.site`  | `https://product.site.synapse.example` |
+
+Custom domains are valid when they route to the corresponding Convex surface.
+The control-plane operator must add each custom functions origin to
+`RASTRO_FEDERATION_ALLOWED_DEPLOYMENT_ORIGINS` as an exact, comma-separated
+HTTPS origin before it can be registered. Do not derive one URL by appending
+paths to the other or derive the allowlist from browser input. If the dashboard
+returns `UNTRUSTED_DEPLOYMENT_HOST`, stop and ask the Amage Rastro operator who
+issued the organization access to add the exact functions origin. Provide only
+that public HTTPS origin, never credentials; retry after the operator confirms
+the allowlist update.
+
+## 3. Create the pending connection
+
+In the central dashboard:
+
+1. Sign in and select the intended organization.
+2. Open **Conexões**.
+3. Enter a recognizable name, the functions URL, and the HTTP URL.
+4. Create the connection, but do not verify it yet.
+5. Copy the displayed issuer, audience, connection ID, and organization ID.
+
+The audience must exactly equal the normalized functions URL. The connection
+remains pending until its local grant is installed and verification succeeds.
+
+## 4. Add the authoritative local grant
+
+Before editing, inventory every existing schema table/index, component mount/env
+declaration, and authentication provider. After editing, prove each remains in
+the diff and typechecks. The snippets in this runbook are insertion fragments,
+not replacement files.
+
+Insert this table property into the pilot project's existing
+`defineSchema({ ... })` object:
+
+```ts
+rastroFederationGrants: defineTable({
+  connectionId: v.string(),
+  organizationId: v.string(),
+  siteIds: v.array(v.string()),
+  revokedAt: v.optional(v.number()),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+}).index("by_connectionId", ["connectionId"]),
+```
+
+The grant, not the JWT, owns the allowed `siteIds`. Add operator-only
+provisioning functions:
+
+```ts
+// convex/rastroFederationAdmin.ts
+import { ConvexError, v } from "convex/values";
+import { Rastro } from "@iann29/rastro";
+import { components } from "./_generated/api";
+import { internalMutation } from "./_generated/server";
+
+const rastro = new Rastro(components.rastroAnalytics);
+
+export const provisionConnection = internalMutation({
+  args: {
+    connectionId: v.string(),
+    organizationId: v.string(),
+    ownerId: v.string(),
+    siteIds: v.array(v.string()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const siteIds = [...new Set(args.siteIds)];
+    if (
+      args.connectionId.length === 0 ||
+      args.connectionId.length > 128 ||
+      args.organizationId.length === 0 ||
+      args.organizationId.length > 128 ||
+      siteIds.length === 0 ||
+      siteIds.length > 10 ||
+      siteIds.length !== args.siteIds.length
+    ) {
+      throw new ConvexError({ code: "INVALID_FEDERATION_GRANT" });
+    }
+
+    for (const siteId of siteIds) {
+      const site = await rastro.getSite(ctx, siteId);
+      if (!site || site.ownerId !== args.ownerId) {
+        throw new ConvexError({ code: "FEDERATION_SITE_NOT_OWNED" });
+      }
+    }
+
+    const existing = await ctx.db
+      .query("rastroFederationGrants")
+      .withIndex("by_connectionId", (query) =>
+        query.eq("connectionId", args.connectionId),
+      )
+      .unique();
+    const now = Date.now();
+    const grant = {
+      connectionId: args.connectionId,
+      organizationId: args.organizationId,
+      siteIds,
+      revokedAt: undefined,
+      updatedAt: now,
+    };
+    if (existing) {
+      await ctx.db.patch("rastroFederationGrants", existing._id, grant);
+    } else {
+      await ctx.db.insert("rastroFederationGrants", {
+        ...grant,
+        createdAt: now,
+      });
+    }
+    return null;
+  },
+});
+
+export const revokeConnection = internalMutation({
+  args: { connectionId: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const grant = await ctx.db
+      .query("rastroFederationGrants")
+      .withIndex("by_connectionId", (query) =>
+        query.eq("connectionId", args.connectionId),
+      )
+      .unique();
+    if (!grant) {
+      throw new ConvexError({ code: "FEDERATION_GRANT_NOT_FOUND" });
+    }
+    if (grant.revokedAt === undefined) {
+      const now = Date.now();
+      await ctx.db.patch("rastroFederationGrants", grant._id, {
+        revokedAt: now,
+        updatedAt: now,
+      });
+    }
+    return null;
+  },
+});
+```
+
+These mutations are `internalMutation`s so a browser cannot call them. Run them
+only with deployment administrator credentials. A host that needs self-service
+pairing may wrap equivalent logic in its own authenticated owner/admin mutation;
+never accept an owner or user ID from an untrusted caller.
+
+## 5. Trust the federation issuer
+
+The displayed issuer must exactly equal the independently verified production
+manifest issuer, `https://site.api.amagerastro.com/federation`; abort on any
+mismatch. Derive the audience locally from the normalized functions URL and
+compare it with the displayed audience. For Convex Cloud DEV:
+
+```bash
+npx convex env set --deployment dev RASTRO_FEDERATION_ISSUER \
+  'https://site.api.amagerastro.com/federation'
+npx convex env set --deployment dev RASTRO_FEDERATION_AUDIENCE \
+  'https://product.convex.cloud'
+```
+
+Use `--deployment prod` only with fresh production consent. For an existing
+Synapse-managed deployment, target its live Convex environment explicitly:
+
+```bash
+synapse convex --dev env set \
+  RASTRO_FEDERATION_ISSUER 'https://site.api.amagerastro.com/federation'
+synapse convex --dev env set \
+  RASTRO_FEDERATION_AUDIENCE 'https://product.synapse.example'
+```
+
+Use `synapse env set NAME=value --for=dev` only when defining project defaults
+before a new deployment is created; defaults do not update an existing live
+deployment.
+
+Insert only these two properties into the pilot project's existing
+`defineApp({ env: { ... } })` object. If no `env` object exists, add it without
+changing any other `defineApp` option. Do not add a second Rastro mount:
+
+```ts
+RASTRO_FEDERATION_ISSUER: v.string(),
+RASTRO_FEDERATION_AUDIENCE: v.string(),
+```
+
+Insert this conditional spread into the existing `providers` array; never
+replace the array or its current entries:
+
+```ts
+// convex/auth.config.ts
+import type { AuthConfig } from "convex/server";
+
+const issuer = process.env.RASTRO_FEDERATION_ISSUER;
+const audience = process.env.RASTRO_FEDERATION_AUDIENCE;
+
+...(issuer && audience
+  ? [
+      {
+        domain: issuer.replace(/\/$/, ""),
+        applicationID: audience.replace(/\/$/, ""),
+      },
+    ]
+  : []),
+```
+
+An exact issuer mismatch is rejected even when the JWT signature is otherwise
+valid. Convex discovers keys from `<issuer>/.well-known/openid-configuration`.
+
+## 6. Expose the read-only host module
+
+Create the canonical module with this exact filename:
+
+```ts
+// convex/rastroFederation.ts
+import {
+  exposeFederatedAnalyticsApi,
+  type FederatedAnalyticsConnection,
+} from "@iann29/rastro";
+import { components } from "./_generated/api";
+import { env, type QueryCtx } from "./_generated/server";
+
+const federated = exposeFederatedAnalyticsApi(components.rastroAnalytics, {
+  issuer: env.RASTRO_FEDERATION_ISSUER.replace(/\/$/, ""),
+  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,
+      revokedAt: grant.revokedAt,
+    } satisfies FederatedAnalyticsConnection;
+  },
+});
+
+export const {
+  manifest,
+  connectionStatus,
+  listSites,
+  overview,
+  liveVisitors,
+  listSessions,
+  sessionJourney,
+  listConversions,
+  visitorJourney,
+  goalsReport,
+  funnelsReport,
+  affiliatesReport,
+  dataCoverage,
+} = federated;
+```
+
+The manifest is public static metadata. Every other function is read-only and
+requires both a valid JWT and a matching non-revoked local grant.
+
+## 7. Deploy and provision
+
+Push the customer host changes first:
+
+```bash
+# Convex Cloud DEV, one push
+npx convex dev --once
+
+# Synapse DEV
+synapse dev --once
+```
+
+Then provision the exact site scope. Replace every placeholder with values
+copied from the pending connection and the host's existing site records:
+
+```bash
+# Convex Cloud DEV
+npx convex run --deployment dev rastroFederationAdmin:provisionConnection \
+  '{"connectionId":"CONNECTION_ID","organizationId":"ORGANIZATION_ID","ownerId":"OPAQUE_HOST_OWNER_ID","siteIds":["SITE_ID"]}'
+
+# Synapse DEV
+synapse convex --dev run rastroFederationAdmin:provisionConnection \
+  '{"connectionId":"CONNECTION_ID","organizationId":"ORGANIZATION_ID","ownerId":"OPAQUE_HOST_OWNER_ID","siteIds":["SITE_ID"]}'
+```
+
+Use the corresponding explicit production target only after rehearsing DEV. The
+command is idempotent for one `connectionId` and replaces its site scope.
+
+## 8. Verify in order
+
+1. Run `rastroFederation:manifest` without auth and confirm protocol version 1.
+2. Return to **Conexões** in the central dashboard.
+3. Click **Verificar conexão**.
+4. Confirm the connection becomes active and reports the expected site count.
+5. Open Visão geral and confirm the deployment selector names the new host.
+6. Trigger one real browser pageview and confirm Ao vivo updates reactively.
+7. Check Metas/Afiliados with a complete UTC-day range when those features are
+   configured.
+
+The central verification signs a short-lived RS256 token, calls authenticated
+`connectionStatus` and `listSites`, and refuses incompatible manifests or
+inconsistent site counts.
+
+## 9. Revoke safely
+
+For immediate denial, revoke the local grant first:
+
+```bash
+npx convex run --deployment dev rastroFederationAdmin:revokeConnection \
+  '{"connectionId":"CONNECTION_ID"}'
+
+# Synapse DEV
+synapse convex --dev run rastroFederationAdmin:revokeConnection \
+  '{"connectionId":"CONNECTION_ID"}'
+```
+
+For production, repeat the rehearsed command with the platform's explicit
+production target: `npx convex run --deployment prod ...` or
+`synapse convex --prod run ...`. Never infer the target from the current shell
+state.
+
+Then revoke the connection in the central dashboard. Central revocation stops
+new tokens; local revocation rejects already-issued tokens immediately. Without
+the local step, an existing token remains usable until its ten-minute expiry.
+
+## Troubleshooting
+
+| Symptom or code                | Check                                                                         |
+| ------------------------------ | ----------------------------------------------------------------------------- |
+| Manifest not found             | File must be `convex/rastroFederation.ts`; deploy/codegen must have completed |
+| `FEDERATION_UNAUTHENTICATED`   | Federation provider missing, token absent, or deployment not redeployed       |
+| `FEDERATION_ISSUER_MISMATCH`   | `auth.config.ts` domain and helper issuer differ, often by a trailing slash   |
+| JWT audience failure           | `RASTRO_FEDERATION_AUDIENCE` must equal the functions URL, not the HTTP URL   |
+| `FEDERATION_CONNECTION_DENIED` | Grant missing, organization mismatched, empty, malformed, or revoked          |
+| `FEDERATION_SITE_DENIED`       | Dashboard requested a site outside the local grant                            |
+| Tracker 404                    | Tracker uses the functions URL instead of the HTTP-actions URL                |
+| `ORIGIN_NOT_ALLOWED`           | Browser host is absent from the site's exact/wildcard domains                 |
+| `REPORT_INCOMPLETE`            | Use complete UTC buckets or reduce a range that exceeds a bounded read budget |
+| `UNTRUSTED_DEPLOYMENT_HOST`    | Ask the control-plane operator to allow the exact custom functions origin     |
+
+Do not fix authorization errors by weakening the resolver, copying site IDs into
+JWT claims, or exposing a permissive report API.

package/docs/federation.md

@@ -0,0 +1,258 @@
+# 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.
+
+The exact generated surface is:
+
+- `manifest`
+- `connectionStatus`
+- `listSites`
+- `overview`
+- `liveVisitors`
+- `listSessions`
+- `sessionJourney`
+- `listConversions`
+- `visitorJourney`
+- `goalsReport`
+- `funnelsReport`
+- `affiliatesReport`
+- `dataCoverage`
+
+There are no ingestion, configuration-write, retention-write, raw-site, or site
+mutation functions in this surface. 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, 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`, and `cookieless`. In particular,
+it never returns `ownerId`, `domains`, or `networkId`.
+
+## 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`    |
+
+Claim names and the permission constant are exported as
+`FEDERATED_ANALYTICS_CLAIMS` and `FEDERATED_ANALYTICS_READ_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()),
+    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.
+
+## Host API
+
+```ts
+// convex/rastroFederation.ts
+import {
+  exposeFederatedAnalyticsApi,
+  type FederatedAnalyticsConnection,
+} from "@iann29/rastro";
+import { components } from "./_generated/api";
+import { env, type QueryCtx } from "./_generated/server";
+
+const federated = exposeFederatedAnalyticsApi(components.rastroAnalytics, {
+  issuer: env.RASTRO_FEDERATION_ISSUER.replace(/\/$/, ""),
+  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,
+      revokedAt: grant.revokedAt,
+    } satisfies FederatedAnalyticsConnection;
+  },
+});
+
+export const {
+  manifest,
+  connectionStatus,
+  listSites,
+  overview,
+  liveVisitors,
+  listSessions,
+  sessionJourney,
+  listConversions,
+  visitorJourney,
+  goalsReport,
+  funnelsReport,
+  affiliatesReport,
+  dataCoverage,
+} = 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.
+
+## 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     |
+
+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.
+- 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, raw site configuration, and every write are absent.
+- `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 `example/` provide Better Auth sessions,
+organization-scoped connections, OIDC discovery, JWKS, ten-minute RS256 tokens,
+manifest verification, redacted site discovery, audit records, revocation of new
+token issuance, and dynamic browser subscriptions to active deployments.
+
+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.