@stigmer/server 3.16.1-dev.20260917224426 → 3.17.0

package/src/extensions/drivers.ts

@@ -53,6 +53,7 @@ import type { RunnerCredentialProvider } from "../runnerauth/runner-credential-p
 import type { SandboxProvisionerFactory } from "../sandbox/provisioner.js";
 import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
+import type { LicenseStatusProvider } from "./license-status.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { OrganizationDirectory } from "./organization-directory.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
@@ -219,4 +220,14 @@ export interface ExtensionDrivers {
    * with the edition reason — the identityFederation absent shape.
    */
   readonly authorizationQueries?: AuthorizationQueryEngine;
+  /**
+   * The license-status provider (single-instance point): what license
+   * this server holds, answered by PlatformQueryController.getLicenseStatus
+   * in every edition. An Enterprise unit registers the provider that
+   * verifies its configured ticket; when absent, the built-in `absent`
+   * answer installs at the compose.ts consumption site, so open source
+   * and the cloud (which hold no key) answer the same question the same
+   * way (extensions/license-status.ts carries the contract).
+   */
+  readonly licenseStatus?: LicenseStatusProvider;
 }

package/src/extensions/license-status.ts

@@ -0,0 +1,71 @@
+/**
+ * The license-status extension point: what license does this server hold?
+ *
+ * Every edition answers the question through
+ * PlatformQueryController.getLicenseStatus, because a server's license is a
+ * fact about the server, like its edition, and the console banner that
+ * reads it ("licensed to Acme until March") must work wherever it is shown.
+ * Only one edition ever has a license to report: the Enterprise composition
+ * registers the provider that verifies the ticket it was configured with.
+ * Open source and the cloud hold no key, so with no provider composed the
+ * built-in `absent` answer below installs at the boot/compose.ts
+ * consumption site (the default-lives-with-the-consumer doctrine; see
+ * drivers.ts).
+ *
+ * The port speaks the generated claim types rather than a domain twin. The
+ * claims ARE the wire — the ticket's payload is the proto JSON of
+ * LicenseClaims — so a hand-written copy would be exactly the duplicate of a
+ * generated type the SDK and server guides forbid.
+ *
+ * The controller owns the clock: it hands the provider ONE instant and
+ * stamps the answer's checked_at from the same one, so a report and its
+ * timestamp can never disagree about when the license was evaluated. A
+ * provider therefore takes `now` and never reads the wall clock itself.
+ *
+ * The report is a union keyed on the state, not a bag of optional fields,
+ * so the wire's presence contract (GetLicenseStatusOutput) is a fact the
+ * compiler holds rather than a sentence a provider has to remember: an
+ * `invalid` report cannot carry the claims that did not verify, a `valid`
+ * one cannot omit them, and `unspecified` cannot be reported at all.
+ */
+import type { LicenseClaims } from "@stigmer/protos/ai/stigmer/platform/v1/license_pb";
+import { LicenseState } from "@stigmer/protos/ai/stigmer/platform/v1/license_pb";
+
+/**
+ * The states in which a ticket's signature verified and its claims are
+ * trusted; what separates them is only where the clock stands in the term.
+ */
+export type VerifiedLicenseState =
+  | LicenseState.valid
+  | LicenseState.expiring
+  | LicenseState.grace
+  | LicenseState.expired;
+
+/**
+ * A provider's answer, evaluated at the instant it was given. One arm per
+ * presence shape: no ticket configured; a ticket that named a key and did
+ * not verify; a ticket that verified, with the key it named and the claims
+ * it carried. The controller copies the arm to the wire field for field.
+ */
+export type LicenseStatusReport =
+  | { readonly state: LicenseState.absent }
+  | { readonly state: LicenseState.invalid; readonly keyId: string }
+  | {
+      readonly state: VerifiedLicenseState;
+      readonly keyId: string;
+      readonly claims: LicenseClaims;
+    };
+
+/** The provider contract (single-instance point, ExtensionDrivers.licenseStatus). */
+export interface LicenseStatusProvider {
+  /** The license's state as of `now`, the instant the answer is stamped with. */
+  status(now: Date): Promise<LicenseStatusReport>;
+}
+
+/**
+ * The built-in answer for a server that holds no license: open source and
+ * the cloud, and an Enterprise composition that registered no provider.
+ */
+export const ABSENT_LICENSE_STATUS: LicenseStatusProvider = {
+  status: () => Promise.resolve({ state: LicenseState.absent }),
+};

package/src/extensions/registry.ts

@@ -53,6 +53,7 @@ import type { SecretCodec } from "../encryption/codec.js";
 import { V1_VERSION } from "../encryption/v1-codec.js";
 import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
+import type { LicenseStatusProvider } from "./license-status.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
 import type { ModelCatalogProvider } from "../domain/workflow/registry/model-catalog-provider.js";
@@ -272,6 +273,11 @@ export interface ResolvedExtensionDrivers {
    * tuple-half RPC arms refuse UNIMPLEMENTED with the edition reason.
    */
   readonly authorizationQueries: AuthorizationQueryEngine | undefined;
+  /**
+   * The license-status provider — undefined = compose.ts installs the
+   * built-in `absent` answer, so every edition serves getLicenseStatus.
+   */
+  readonly licenseStatus: LicenseStatusProvider | undefined;
 }
 
 /**
@@ -325,6 +331,8 @@ export function resolveExtensions(
   let policyGrantScopeDeclaredBy: string | undefined;
   let authorizationQueries: AuthorizationQueryEngine | undefined;
   let authorizationQueriesDeclaredBy: string | undefined;
+  let licenseStatus: LicenseStatusProvider | undefined;
+  let licenseStatusDeclaredBy: string | undefined;
   const artifactStorageDrivers = new Map<
     string,
     ArtifactStorageDriverFactory
@@ -516,6 +524,16 @@ export function resolveExtensions(
       authorizationQueriesDeclaredBy = unit.name;
     }
 
+    if (unit.drivers?.licenseStatus !== undefined) {
+      if (licenseStatusDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers a LicenseStatusProvider, but '${licenseStatusDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      licenseStatus = unit.drivers.licenseStatus;
+      licenseStatusDeclaredBy = unit.name;
+    }
+
     if (unit.drivers?.artifactStorageDrivers !== undefined) {
       for (const [name, factory] of unit.drivers.artifactStorageDrivers) {
         if ((BUILT_IN_STORAGE_TYPES as ReadonlyArray<string>).includes(name)) {
@@ -641,6 +659,7 @@ export function resolveExtensions(
       iamPolicyStore,
       policyGrantScope,
       authorizationQueries,
+      licenseStatus,
     },
     services,
     workers,

package/src/index.ts

@@ -111,6 +111,14 @@ export type {
 } from "./extensions/resource-authorization.js";
 export type { OrganizationDirectory } from "./extensions/organization-directory.js";
 export { ALL_ORGANIZATIONS } from "./extensions/organization-directory.js";
+// The license-status seam (drivers.licenseStatus): the provider an
+// Enterprise composition registers so getLicenseStatus answers from its
+// configured ticket. The built-in `absent` default is the composition
+// root's and is not exported.
+export type {
+  LicenseStatusProvider,
+  LicenseStatusReport,
+} from "./extensions/license-status.js";
 // The 20260911.11 identity-account seams (Q-IA-9): the store PORT a
 // composition drives the domain through (drivers.identityAccountStore;
 // a driver throws DuplicateAccountError for a held id), the federation

package/src/pipeline/__tests__/billing-contract-rules.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Pins the message-level rules of the plan, subscription and license
+ * contract through the shared validator every edition runs
+ * (steps/validation.ts, the same instance the transport interceptor uses).
+ *
+ * Why here and not in a conformance suite: every billing kind is cloud_only,
+ * so the open-source server never serves a Plan or a License and the
+ * cross-edition suites, where field rules are normally proven against a
+ * running server, cannot reach them. The vocabulary those kinds share with
+ * the Enterprise edition (Entitlements, LicenseClaims) is verified offline
+ * by a server that holds no store for it at all. The one place in this
+ * repository where a rule on these messages can be proven red-then-green is
+ * the validator itself, so this file drives it directly, one row per rule,
+ * a passing shape beside every refused one.
+ *
+ * What the rows pin: the instrument decides which PlanTerms a plan may carry;
+ * a license's timestamps are ordered (issue, expiry, grace); a limit is
+ * present or absent, never zero; a feature is named once. A row that
+ * stops matching means the contract moved, and the proto is where it moved.
+ */
+import { create } from "@bufbuild/protobuf";
+import type { DescMessage, MessageInitShape } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import {
+  PlanInstrument,
+  PlanSpecSchema,
+} from "@stigmer/protos/ai/stigmer/billing/plan/v1/spec_pb";
+import { LicenseSpecSchema } from "@stigmer/protos/ai/stigmer/billing/license/v1/spec_pb";
+import {
+  EntitlementLimitsSchema,
+  EntitlementsSchema,
+  Feature,
+} from "@stigmer/protos/ai/stigmer/platform/v1/entitlement_pb";
+import {
+  LicenseClaimsSchema,
+  LicenseTerm,
+} from "@stigmer/protos/ai/stigmer/platform/v1/license_pb";
+import { describe, expect, it } from "vitest";
+
+import { validator } from "../steps/validation.js";
+
+const t = (iso: string) => timestampFromDate(new Date(iso));
+
+const customer = {
+  id: "cus_acme",
+  displayName: "Acme Corp",
+  contactEmail: "billing@acme.example",
+};
+const entitlements = { features: [Feature.channels] };
+const orderedTerm = {
+  issuedAt: t("2026-09-01T00:00:00Z"),
+  expiresAt: t("2027-09-01T00:00:00Z"),
+  graceUntil: t("2027-10-01T00:00:00Z"),
+};
+
+/** One row: a message, its init, and the rule id it must trip, or none. */
+interface Row<Desc extends DescMessage> {
+  readonly name: string;
+  readonly schema: Desc;
+  readonly init: MessageInitShape<Desc>;
+  readonly refusedBy?: string;
+}
+
+function row<Desc extends DescMessage>(r: Row<Desc>): Row<Desc> {
+  return r;
+}
+
+const rows: ReadonlyArray<Row<DescMessage>> = [
+  row({
+    name: "a subscription plan with monthly terms",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.subscription,
+      entitlements,
+      terms: { monthlyMinimumMicros: 1n, usageShareBasisPoints: 100 },
+    },
+  }),
+  row({
+    name: "a license plan with an annual price",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.license,
+      entitlements,
+      terms: { annualPriceMicros: 1n },
+    },
+  }),
+  row({
+    name: "a plan with no terms at all",
+    schema: PlanSpecSchema,
+    init: { instrument: PlanInstrument.subscription, entitlements },
+  }),
+  row({
+    name: "a license plan carrying a monthly minimum",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.license,
+      entitlements,
+      terms: { monthlyMinimumMicros: 1n },
+    },
+    refusedBy: "plan_spec.license_has_no_monthly_terms",
+  }),
+  row({
+    name: "a license plan carrying a usage share",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.license,
+      entitlements,
+      terms: { usageShareBasisPoints: 100 },
+    },
+    refusedBy: "plan_spec.license_has_no_monthly_terms",
+  }),
+  row({
+    name: "a subscription plan carrying an annual price",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.subscription,
+      entitlements,
+      terms: { annualPriceMicros: 1n },
+    },
+    refusedBy: "plan_spec.subscription_has_no_annual_price",
+  }),
+  row({
+    name: "a usage share above one hundred percent",
+    schema: PlanSpecSchema,
+    init: {
+      instrument: PlanInstrument.subscription,
+      entitlements,
+      terms: { usageShareBasisPoints: 10001 },
+    },
+    refusedBy: "int32.gte_lte",
+  }),
+  row({
+    name: "ordered license claims",
+    schema: LicenseClaimsSchema,
+    init: {
+      licenseId: "lic_1",
+      customer,
+      term: LicenseTerm.paid,
+      entitlements,
+      ...orderedTerm,
+    },
+  }),
+  row({
+    name: "claims expiring before they were issued",
+    schema: LicenseClaimsSchema,
+    init: {
+      licenseId: "lic_1",
+      customer,
+      term: LicenseTerm.paid,
+      entitlements,
+      ...orderedTerm,
+      expiresAt: t("2026-08-01T00:00:00Z"),
+      graceUntil: t("2026-08-02T00:00:00Z"),
+    },
+    refusedBy: "license_claims.expires_after_issue",
+  }),
+  row({
+    name: "claims whose grace ends before expiry",
+    schema: LicenseClaimsSchema,
+    init: {
+      licenseId: "lic_1",
+      customer,
+      term: LicenseTerm.paid,
+      entitlements,
+      ...orderedTerm,
+      graceUntil: t("2027-08-01T00:00:00Z"),
+    },
+    refusedBy: "license_claims.grace_not_before_expiry",
+  }),
+  row({
+    name: "a customer with no contact address",
+    schema: LicenseClaimsSchema,
+    init: {
+      licenseId: "lic_1",
+      customer: { id: "cus_acme", displayName: "Acme Corp" },
+      term: LicenseTerm.paid,
+      entitlements,
+      ...orderedTerm,
+    },
+    refusedBy: "required",
+  }),
+  row({
+    name: "a customer whose contact address is not an email",
+    schema: LicenseClaimsSchema,
+    init: {
+      licenseId: "lic_1",
+      customer: { ...customer, contactEmail: "acme" },
+      term: LicenseTerm.paid,
+      entitlements,
+      ...orderedTerm,
+    },
+    refusedBy: "string.email",
+  }),
+  row({
+    name: "a license spec whose grace ends before expiry",
+    schema: LicenseSpecSchema,
+    init: {
+      customer,
+      entitlements,
+      term: LicenseTerm.trial,
+      expiresAt: orderedTerm.expiresAt,
+      graceUntil: t("2027-08-01T00:00:00Z"),
+    },
+    refusedBy: "license_spec.grace_not_before_expiry",
+  }),
+  row({
+    name: "a license spec with grace on the expiry instant",
+    schema: LicenseSpecSchema,
+    init: {
+      customer,
+      entitlements,
+      term: LicenseTerm.trial,
+      expiresAt: orderedTerm.expiresAt,
+      graceUntil: orderedTerm.expiresAt,
+    },
+  }),
+  row({
+    name: "a limit of zero, which is never what an operator meant",
+    schema: EntitlementLimitsSchema,
+    init: { maxOrganizations: 0 },
+    refusedBy: "int32.gt",
+  }),
+  row({
+    name: "an absent limit, which is no limit",
+    schema: EntitlementLimitsSchema,
+    init: {},
+  }),
+  row({
+    name: "a feature named twice",
+    schema: EntitlementsSchema,
+    init: { features: [Feature.channels, Feature.channels] },
+    refusedBy: "repeated.unique",
+  }),
+  row({
+    name: "the unspecified feature",
+    schema: EntitlementsSchema,
+    init: { features: [Feature.feature_unspecified] },
+    refusedBy: "enum.not_in",
+  }),
+];
+
+describe("the billing contract's rules, through the shared validator", () => {
+  for (const r of rows) {
+    const verdict =
+      r.refusedBy === undefined ? "passes" : `is refused by ${r.refusedBy}`;
+    it(`${r.name} ${verdict}`, () => {
+      const result = validator().validate(r.schema, create(r.schema, r.init));
+      if (r.refusedBy === undefined) {
+        expect(result.kind).toBe("valid");
+        return;
+      }
+      if (result.kind !== "invalid") {
+        throw new Error(`expected a refusal, got ${result.kind}`);
+      }
+      expect(result.error.violations.map((v) => v.ruleId)).toContain(
+        r.refusedBy,
+      );
+    });
+  }
+});