@tryvitris/website-admin-contracts 1.1.0 → 1.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Vitris contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Vitris contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Website Admin Contracts
-
-Validated installation manifests, roles, permissions and module contracts for `@tryvitris/website-admin-harness`. Node.js 24+. MIT licensed.
+# Website Admin Contracts
+
+Validated installation manifests, roles, permissions and module contracts for `@tryvitris/website-admin-harness`. Node.js 24+. MIT licensed.

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export * from './client-portfolio.js';
 export * from './client-onboarding.js';
 export * from './scheduling.js';
 export * from './webmaster.js';
+export * from './pairing.js';
+export * from './signon.js';
 export declare const contractVersion = 1;
 export declare const coreSections: readonly ["overview", "leads", "analytics", "settings", "access", "activity"];
 export declare const permissions: readonly ["leads:read", "leads:write", "analytics:read", "settings:write", "access:read", "access:write", "activity:read", "tasks:read", "tasks:write", "appointments:read", "appointments:write", "availability:write", "scheduling:configure", "calendar-connections:manage", "clients:read", "client-changes:request", "client-releases:publish", "prospects:read", "prospects:write", "billing:read", "billing:customers:write", "billing:catalog:read", "billing:subscriptions:write", "billing:invoices:write", "billing:collect", "billing:connection:manage", "account-billing:read", "account-billing:manage"];
@@ -12,6 +14,8 @@ export type Role = 'owner' | 'administrator' | 'editor' | 'analyst';
 export declare const roles: Record<Role, readonly Permission[]>;
 export declare function can(role: Role, permission: Permission): boolean;
 export interface AdminManifest {
+    webmasterSignOn?: import('./signon.js').SignOnConfiguration;
+    reportingPairing?: import('./pairing.js').PairingConfiguration;
     schemaVersion: 1;
     installationId: string;
     business: {

package/dist/index.js

@@ -8,6 +8,8 @@ export * from "./client-portfolio.js";
 export * from "./client-onboarding.js";
 export * from "./scheduling.js";
 export * from "./webmaster.js";
+export * from "./pairing.js";
+export * from "./signon.js";
 const contractVersion = 1;
 const coreSections = ["overview", "leads", "analytics", "settings", "access", "activity"];
 const permissions = ["leads:read", "leads:write", "analytics:read", "settings:write", "access:read", "access:write", "activity:read", "tasks:read", "tasks:write", ...schedulingPermissions, ...clientPortfolioPermissions, ...clientOnboardingPermissions, ...billingPermissions];
@@ -118,6 +120,29 @@ function parseManifest(value) {
     backend = { provider: "vitris-harness", origin: origin(b.origin, "backend origin"), tenantId };
     if (isLoopback(backend.origin) && !isLoopback(String(v.adminOrigin))) throw new Error("Production admin cannot connect to a local backend");
   }
+  let reportingPairing;
+  if (v.reportingPairing !== void 0) {
+    const config = object(v.reportingPairing);
+    if (!Array.isArray(config.trustedWebmasters) || config.trustedWebmasters.length < 1 || config.trustedWebmasters.length > 10) throw new Error("Configure trusted webmaster installations explicitly");
+    const trustedWebmasters = config.trustedWebmasters.map((raw) => {
+      const p = object(raw), adminOrigin = origin(p.adminOrigin, "trusted webmaster origin");
+      if (isLoopback(adminOrigin) && !isLoopback(String(v.adminOrigin))) throw new Error("A production issuer cannot trust a local webmaster");
+      return { installationId: id(p.installationId, "webmaster installation ID"), siteId: id(p.siteId, "webmaster site ID"), adminOrigin, organizationId: id(p.organizationId, "webmaster organization ID"), organizationName: text(p.organizationName, "webmaster organization name") };
+    });
+    if (new Set(trustedWebmasters.map((p) => p.adminOrigin)).size !== trustedWebmasters.length) throw new Error("Duplicate trusted webmaster origin");
+    reportingPairing = { trustedWebmasters };
+  }
+  let webmasterSignOn;
+  if (v.webmasterSignOn !== void 0) {
+    const c = object(v.webmasterSignOn);
+    if (c.mode === "broker") webmasterSignOn = { mode: "broker" };
+    else if (c.mode === "client") {
+      const b = object(c.broker), k = object(c.publicKey), adminOrigin = origin(b.adminOrigin, "sign-on broker origin");
+      if (isLoopback(adminOrigin) && !isLoopback(String(v.adminOrigin))) throw Error("A production client cannot trust a local sign-on broker");
+      if (k.kty !== "EC" || k.crv !== "P-256" || typeof k.x !== "string" || typeof k.y !== "string" || !/^[-\w]{43}$/.test(k.x) || !/^[-\w]{43}$/.test(k.y) || k.d !== void 0) throw Error("Pin the broker public P-256 key");
+      webmasterSignOn = { mode: "client", broker: { installationId: id(b.installationId, "broker installation ID"), siteId: id(b.siteId, "broker site ID"), adminOrigin }, subjectId: text(c.subjectId, "approved broker subject", 100), organizationId: id(c.organizationId, "webmaster organization ID"), publicKey: { kty: "EC", crv: "P-256", x: k.x, y: k.y } };
+    } else throw Error("Unsupported webmaster sign-on mode");
+  }
   return {
     schemaVersion: 1,
     installationId: id(v.installationId, "installation ID"),
@@ -126,7 +151,9 @@ function parseManifest(value) {
     adminOrigin: origin(v.adminOrigin, "admin origin"),
     modules,
     ...backend ? { backend } : {},
-    ...v.theme ? { theme: v.theme } : {}
+    ...v.theme ? { theme: v.theme } : {},
+    ...reportingPairing ? { reportingPairing } : {},
+    ...webmasterSignOn ? { webmasterSignOn } : {}
   };
 }
 function validateModules(manifest, modules) {

package/dist/pairing.d.ts

@@ -0,0 +1,94 @@
+export declare const reportingPairingVersion = 1;
+export declare const pairingBase = "/api/webmaster-reporting/v1";
+export declare const pairingMachineActions: readonly ["request", "poll", "exchange", "report", "rotate", "revoke"];
+export type PairingMachineAction = typeof pairingMachineActions[number];
+export declare const pairingPaths: Record<"capabilities" | "approval" | "approve" | "reject" | "grants" | "revoke-grant" | PairingMachineAction, string>;
+export declare const pairingPolicy: {
+    requestLifetimeSeconds: number;
+    receiptLifetimeSeconds: number;
+    signatureSkewSeconds: number;
+    analyticsDays: readonly [14, 30];
+};
+export interface PairingStart {
+    requestId: string;
+    challenge: string;
+}
+export interface PairingExchange {
+    requestId: string;
+    code: string;
+    verifier: string;
+}
+export interface PairingReportRequest {
+    grantId: string;
+    operation: 'status' | 'analytics';
+    days?: 14 | 30;
+}
+export interface PairingMutation {
+    grantId: string;
+    operationId: string;
+}
+export declare const reportingOperations: readonly ["status", "analytics"];
+export interface PairingIdentity {
+    installationId: string;
+    siteId: string;
+    adminOrigin: string;
+}
+export interface PairingPeer extends PairingIdentity {
+    organizationId: string;
+    organizationName: string;
+}
+export interface PairingConfiguration {
+    trustedWebmasters: PairingPeer[];
+}
+export interface PairingCapabilities {
+    version: 1;
+    issuer: PairingIdentity;
+    siteOrigin: string;
+    operations: readonly ['status', 'analytics'];
+    scope: 'analytics:read';
+    requestPath: string;
+    approvalPath: string;
+}
+export interface PairingEnvelope {
+    version: 1;
+    identity: PairingIdentity;
+    target: string;
+    path: string;
+    time: number;
+    nonce: string;
+    tokenHash: string;
+    request: Record<string, unknown>;
+}
+export interface PairingCredential {
+    version: 1;
+    issuer: PairingIdentity;
+    consumer: PairingIdentity;
+    siteOrigin: string;
+    grantId: string;
+    token: string;
+    keyId: string;
+    scope: 'analytics:read';
+    operations: readonly ['status', 'analytics'];
+}
+export interface PairingGrantView {
+    id: string;
+    organizationId: string;
+    organizationName: string;
+    consumer: PairingIdentity;
+    createdAt: number;
+    lastUsedAt: number | null;
+    revokedAt: number | null;
+    revision: number;
+}
+export interface PairingRequestView {
+    id: string;
+    organizationName: string;
+    consumer: PairingIdentity;
+    issuer: PairingIdentity;
+    expiresAt: number;
+    status: 'pending' | 'approved' | 'revoked' | 'expired';
+    scope: 'analytics:read';
+    createsRelationship: boolean;
+}
+export type PairingErrorCode = 'invalid_request' | 'unauthorized' | 'forbidden' | 'expired' | 'replay' | 'conflict' | 'unavailable' | 'unsupported';
+export declare function samePairingIdentity(a: PairingIdentity, b: PairingIdentity): boolean;

package/dist/pairing.js

@@ -0,0 +1,19 @@
+// packages/contracts/src/pairing.ts
+var reportingPairingVersion = 1;
+var pairingBase = "/api/webmaster-reporting/v1";
+var pairingMachineActions = ["request", "poll", "exchange", "report", "rotate", "revoke"];
+var pairingPaths = Object.fromEntries(["capabilities", "approval", "approve", "reject", "grants", "revoke-grant", ...pairingMachineActions].map((action) => [action, pairingBase + "/" + action]));
+var pairingPolicy = { requestLifetimeSeconds: 600, receiptLifetimeSeconds: 600, signatureSkewSeconds: 90, analyticsDays: [14, 30] };
+var reportingOperations = ["status", "analytics"];
+function samePairingIdentity(a, b) {
+  return a.installationId === b.installationId && a.siteId === b.siteId && a.adminOrigin === b.adminOrigin;
+}
+export {
+  pairingBase,
+  pairingMachineActions,
+  pairingPaths,
+  pairingPolicy,
+  reportingOperations,
+  reportingPairingVersion,
+  samePairingIdentity
+};

package/dist/signon.d.ts

@@ -0,0 +1,51 @@
+import type { PairingIdentity } from './pairing.js';
+export declare const signOnVersion = 1;
+export declare const signOnBase = "/api/webmaster-sso/v1";
+export declare const signOnPolicy: {
+    flowSeconds: number;
+    codeSeconds: number;
+    approvalSeconds: number;
+    sessionSeconds: number;
+    uiCheckMilliseconds: number;
+};
+export type SignOnConfiguration = {
+    mode: 'broker';
+} | {
+    mode: 'client';
+    broker: PairingIdentity;
+    subjectId: string;
+    organizationId: string;
+    publicKey: {
+        kty: 'EC';
+        crv: 'P-256';
+        x: string;
+        y: string;
+    };
+};
+export interface SignOnAssertion {
+    version: 1;
+    issuer: PairingIdentity;
+    audience: PairingIdentity;
+    subject: {
+        id: string;
+        email: string;
+    };
+    lease: string;
+    expiresAt: number;
+    flowId: string;
+}
+export interface SignOnStatus {
+    version: 1;
+    issuer: PairingIdentity;
+    audience: PairingIdentity;
+    nonce: string;
+    leaseHash: string;
+    subjectId: string;
+    active: boolean;
+    expiresAt: number;
+    time: number;
+}
+export interface SignedSignOn {
+    payload: string;
+    signature: string;
+}

package/dist/signon.js

@@ -0,0 +1,9 @@
+// packages/contracts/src/signon.ts
+var signOnVersion = 1;
+var signOnBase = "/api/webmaster-sso/v1";
+var signOnPolicy = { flowSeconds: 300, codeSeconds: 60, approvalSeconds: 600, sessionSeconds: 28800, uiCheckMilliseconds: 5e3 };
+export {
+  signOnBase,
+  signOnPolicy,
+  signOnVersion
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryvitris/website-admin-contracts",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "license": "MIT",
   "description": "Validated installation and module contracts for Cloudflare business admin apps",