@antasphere/chassis-server 1.0.0

package/dist/entitlements/profiles.d.ts

@@ -0,0 +1,121 @@
+import { type EntitlementTier, type ToolEntitlements } from '@antasphere/chassis-contract';
+import type { Logger } from '../logger.js';
+import type { HubMachineToken } from './hub-machine-token.js';
+/**
+ * An account's entitlement profile, resolved: the plan, every declared limit
+ * with the value that applies (the hub's override when it sent one, the
+ * tool's declared value for the tier otherwise), and the features on.
+ */
+export interface ResolvedProfile {
+    plan: EntitlementTier;
+    /** null = unlimited (a tier's null, or a hub `true`); 0 = nothing allowed (a hub `false`). */
+    limits: Record<string, number | null>;
+    features: ReadonlySet<string>;
+    /** Where the plan came from: the hub, the last known answer, or the default. */
+    source: 'hub' | 'stale' | 'default';
+    /**
+     * The hub's upgrade page for the organization (`org`, `tool`, `plan` on it),
+     * when the hub sent one with the plan served here; null when the plan is
+     * the default (never answered, or past the stale window) or the hub is
+     * older than phase 2. The gate appends `key` and `requiredPlan`.
+     */
+    upgradeUrl: string | null;
+}
+export interface EntitlementProfileDials {
+    /** How long a hub answer is served without asking again (§7: 30 s per account). */
+    ttlMs: number;
+    /**
+     * How long the LAST KNOWN plan is kept when the hub stops answering, before
+     * falling to `free` (the federation gate's own posture on hub_unavailable:
+     * 15 minutes). A pro account is not refused above the free cap on every
+     * hub blip.
+     */
+    staleMs: number;
+    /** Hub request budget (the read runs off the request path; this bounds the background fetch). */
+    timeoutMs: number;
+    /**
+     * How long a request waits for the FIRST read of an account nobody asked
+     * the hub about yet (PRDCT-2633). A warm cache never waits: a fresh entry
+     * is served, a stale one is served while a refresh runs behind it. A cold
+     * account waits at most this long, then gets the default (`free`) while the
+     * read finishes in the background — so a pro account is judged right on
+     * its first request whenever the hub answers in time. Every request for a
+     * cold account that arrives while that first read is in flight waits up
+     * to this budget too (each against the one flight), bounded overall by
+     * `timeoutMs`, after which the miss is cached and served at once.
+     */
+    coldWaitMs: number;
+}
+export declare const DEFAULT_PROFILE_DIALS: EntitlementProfileDials;
+export interface EntitlementProfilesOptions {
+    issuerUrl: string;
+    token: HubMachineToken;
+    logger: Logger;
+    dials?: Partial<EntitlementProfileDials> | undefined;
+    fetchImpl?: typeof fetch | undefined;
+    now?: (() => number) | undefined;
+}
+interface CacheEntry {
+    plan: EntitlementTier;
+    /** The hub's overrides as sent: a number, or a boolean switch (`true` unlimited, `false` nothing). */
+    hubLimits: Record<string, number | boolean>;
+    hubFeatures: string[] | null;
+    /** The hub's upgrade page for the organization, when it sent one. */
+    hubUpgradeUrl: string | null;
+    /** When the hub last answered. */
+    answeredAtMs: number;
+    /** Until when this entry is served without a hub call. */
+    freshUntilMs: number;
+}
+/**
+ * The per-account plan on the cloud edition, read from the hub's
+ * `GET /usage/entitlements?accountRef=` with the machine token and cached
+ * 30 s per account. Resolution against the tool's declared tier values
+ * (`resolve`): the hub's rows win over the defaults whenever it sent them.
+ *
+ * The read is OFF the request path (PRDCT-2633, stale-while-revalidate):
+ * a fresh entry is served as it is; an entry past its TTL is served at once
+ * and refreshed behind the request, single-flight per account; only an
+ * account the cache has never seen waits, and at most `coldWaitMs`. A hub
+ * that is slow but alive therefore costs a metered request nothing once the
+ * account is known.
+ *
+ * Failure posture: a hub that does not answer (a 404 from an older hub, a
+ * 5xx, a timeout) keeps the last known plan for `staleMs`, then `free`; an
+ * account the hub never answered for is `free` from the start. Every failure
+ * is cached for `ttlMs` too, so a request storm never becomes a hub storm.
+ */
+export declare class EntitlementProfiles {
+    private readonly opts;
+    private readonly url;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly dials;
+    private readonly cache;
+    private readonly inflight;
+    /** How many reads reached the hub — a test seam. */
+    hubReads: number;
+    constructor(opts: EntitlementProfilesOptions);
+    /** The account's profile, resolved against what the tool declares. */
+    get(accountRef: string, tool: ToolEntitlements): Promise<ResolvedProfile>;
+    /** Forget every cached answer (a test seam). */
+    clear(): void;
+    /** Wait for every background refresh in flight (a test seam). */
+    settle(): Promise<void>;
+    private entry;
+    private refresh;
+    /**
+     * Keep the cache bounded on a long-lived replica: once it holds more than
+     * `SWEEP_ABOVE` accounts, drop every entry that is neither fresh nor
+     * inside its stale window (nothing would be served from it any more).
+     */
+    private sweep;
+    /** One hub read; null on any failure (logged, never thrown). */
+    private read;
+}
+/** The plan a fresh instance assumes, and the resolution every edition path shares. */
+export declare function resolve(tool: ToolEntitlements, entry: CacheEntry | null, nowMs: number, staleMs: number): ResolvedProfile;
+/** The profile of an account nobody asked the hub about: the tool's `free` tier. */
+export declare function defaultProfile(tool: ToolEntitlements): ResolvedProfile;
+export {};
+//# sourceMappingURL=profiles.d.ts.map

package/dist/entitlements/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/entitlements/profiles.ts"],"names":[],"mappings":"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"}

package/dist/entitlements/profiles.js

@@ -0,0 +1,212 @@
+import { entitlementProfileSchema } from '@antasphere/chassis-contract';
+export const DEFAULT_PROFILE_DIALS = {
+    ttlMs: 30_000,
+    staleMs: 15 * 60_000,
+    timeoutMs: 5_000,
+    coldWaitMs: 1_500
+};
+/**
+ * The per-account plan on the cloud edition, read from the hub's
+ * `GET /usage/entitlements?accountRef=` with the machine token and cached
+ * 30 s per account. Resolution against the tool's declared tier values
+ * (`resolve`): the hub's rows win over the defaults whenever it sent them.
+ *
+ * The read is OFF the request path (PRDCT-2633, stale-while-revalidate):
+ * a fresh entry is served as it is; an entry past its TTL is served at once
+ * and refreshed behind the request, single-flight per account; only an
+ * account the cache has never seen waits, and at most `coldWaitMs`. A hub
+ * that is slow but alive therefore costs a metered request nothing once the
+ * account is known.
+ *
+ * Failure posture: a hub that does not answer (a 404 from an older hub, a
+ * 5xx, a timeout) keeps the last known plan for `staleMs`, then `free`; an
+ * account the hub never answered for is `free` from the start. Every failure
+ * is cached for `ttlMs` too, so a request storm never becomes a hub storm.
+ */
+export class EntitlementProfiles {
+    opts;
+    url;
+    fetchImpl;
+    now;
+    dials;
+    cache = new Map();
+    inflight = new Map();
+    /** How many reads reached the hub — a test seam. */
+    hubReads = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.url = opts.issuerUrl.replace(/\/+$/, '') + '/api/v1/usage/entitlements';
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+        this.now = opts.now ?? Date.now;
+        this.dials = { ...DEFAULT_PROFILE_DIALS, ...opts.dials };
+    }
+    /** The account's profile, resolved against what the tool declares. */
+    async get(accountRef, tool) {
+        const entry = await this.entry(accountRef);
+        return resolve(tool, entry, this.now(), this.dials.staleMs);
+    }
+    /** Forget every cached answer (a test seam). */
+    clear() {
+        this.cache.clear();
+    }
+    /** Wait for every background refresh in flight (a test seam). */
+    async settle() {
+        await Promise.all([...this.inflight.values()]);
+    }
+    async entry(accountRef) {
+        const cached = this.cache.get(accountRef);
+        if (cached && cached.freshUntilMs > this.now())
+            return cached;
+        let flight = this.inflight.get(accountRef);
+        if (!flight) {
+            flight = this.refresh(accountRef, cached ?? null).finally(() => {
+                this.inflight.delete(accountRef);
+            });
+            this.inflight.set(accountRef, flight);
+        }
+        // Stale: served now, the refresh runs behind the request.
+        if (cached)
+            return cached;
+        // Cold: wait for the first read, but never longer than the cold budget.
+        await withinBudget(flight, this.dials.coldWaitMs);
+        return this.cache.get(accountRef) ?? null;
+    }
+    async refresh(accountRef, previous) {
+        this.hubReads += 1;
+        this.sweep();
+        const answered = await this.read(accountRef);
+        const now = this.now();
+        if (answered) {
+            // Which features list is the truth. A hub that answers at least one
+            // limit key serves its real rows for this tool (phase 2, PRDCT-2663):
+            // its `features` is then authoritative AS IT IS, an empty list
+            // included, so a per-account override that switches a feature off is
+            // felt. A hub that answers no limit at all is a phase-1 hub (or a tool
+            // it has not seeded yet), whose empty lists mean "the tool applies its
+            // own tier defaults for the plan named here": there a non-empty list
+            // still overrides and an empty one leaves the declared tier values.
+            const authoritative = Object.keys(answered.limits).length > 0;
+            this.cache.set(accountRef, {
+                plan: answered.plan,
+                hubLimits: answered.limits,
+                hubFeatures: authoritative || answered.features.length > 0 ? answered.features : null,
+                hubUpgradeUrl: answered.upgradeUrl ?? null,
+                answeredAtMs: now,
+                freshUntilMs: now + this.dials.ttlMs
+            });
+            return;
+        }
+        // Keep the last answer (its `answeredAtMs` decides staleness), or record
+        // a miss so the next request within the TTL does not ask again.
+        this.cache.set(accountRef, previous
+            ? { ...previous, freshUntilMs: now + this.dials.ttlMs }
+            : {
+                plan: 'free',
+                hubLimits: {},
+                hubFeatures: null,
+                hubUpgradeUrl: null,
+                answeredAtMs: 0,
+                freshUntilMs: now + this.dials.ttlMs
+            });
+    }
+    /**
+     * Keep the cache bounded on a long-lived replica: once it holds more than
+     * `SWEEP_ABOVE` accounts, drop every entry that is neither fresh nor
+     * inside its stale window (nothing would be served from it any more).
+     */
+    sweep() {
+        if (this.cache.size <= SWEEP_ABOVE)
+            return;
+        const now = this.now();
+        for (const [key, entry] of this.cache) {
+            const servable = entry.freshUntilMs > now || (entry.answeredAtMs > 0 && entry.answeredAtMs + this.dials.staleMs > now);
+            if (!servable)
+                this.cache.delete(key);
+        }
+    }
+    /** One hub read; null on any failure (logged, never thrown). */
+    async read(accountRef) {
+        let token;
+        try {
+            token = await this.opts.token.get();
+        }
+        catch (err) {
+            this.opts.logger.warn({ err }, 'entitlements: no machine token — the last known plan applies');
+            return null;
+        }
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.url}?accountRef=${encodeURIComponent(accountRef)}`, {
+                method: 'GET',
+                headers: { accept: 'application/json', authorization: `Bearer ${token}` },
+                signal: AbortSignal.timeout(this.dials.timeoutMs)
+            });
+        }
+        catch (err) {
+            this.opts.logger.warn({ err }, 'entitlements: hub unreachable — the last known plan applies');
+            return null;
+        }
+        if (res.status === 401)
+            this.opts.token.invalidate();
+        if (!res.ok) {
+            this.opts.logger.warn({ status: res.status }, 'entitlements: hub answered non-2xx — the last known plan applies');
+            return null;
+        }
+        const parsed = entitlementProfileSchema.safeParse(await res.json().catch(() => null));
+        if (!parsed.success) {
+            this.opts.logger.warn('entitlements: hub answered a malformed profile — the last known plan applies');
+            return null;
+        }
+        return parsed.data;
+    }
+}
+/** The plan a fresh instance assumes, and the resolution every edition path shares. */
+export function resolve(tool, entry, nowMs, staleMs) {
+    const known = entry && entry.answeredAtMs > 0;
+    const stale = known && entry.answeredAtMs + staleMs <= nowMs;
+    const plan = known && !stale ? entry.plan : 'free';
+    const source = !known || stale ? 'default' : entry.freshUntilMs > nowMs ? 'hub' : 'stale';
+    const limits = {};
+    for (const [key, tiers] of Object.entries(tool.limits)) {
+        const override = known && !stale ? entry.hubLimits[key] : undefined;
+        limits[key] = override !== undefined ? limitValue(override) : tiers[plan];
+    }
+    const features = new Set();
+    const hubFeatures = known && !stale ? entry.hubFeatures : null;
+    for (const [key, tiers] of Object.entries(tool.features)) {
+        if (hubFeatures ? hubFeatures.includes(key) : tiers[plan])
+            features.add(key);
+    }
+    const upgradeUrl = known && !stale ? entry.hubUpgradeUrl : null;
+    return { plan, limits, features, source, upgradeUrl };
+}
+/**
+ * A hub limit value as the gate compares it (PRDCT-2636): the hub's contract
+ * allows a boolean beside a number — `true` switches the limit off
+ * (unlimited, null), `false` allows nothing (0).
+ */
+function limitValue(value) {
+    if (value === true)
+        return null;
+    if (value === false)
+        return 0;
+    return value;
+}
+/** How many accounts the cache may hold before a refresh sweeps the unservable entries. */
+const SWEEP_ABOVE = 5_000;
+/** Resolve when `flight` settles or `ms` elapse, whichever first; the timer never outlives the wait. */
+function withinBudget(flight, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.(); // a pending wait must never keep the process alive
+        void flight.finally(() => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}
+/** The profile of an account nobody asked the hub about: the tool's `free` tier. */
+export function defaultProfile(tool) {
+    return resolve(tool, null, 0, 0);
+}
+//# sourceMappingURL=profiles.js.map

package/dist/entitlements/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../src/entitlements/profiles.ts"],"names":[],"mappings":"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"}

package/dist/entitlements/slot.d.ts

@@ -0,0 +1,33 @@
+import { type RouteEntitlementDeclarations, type ToolEntitlements } from '@antasphere/chassis-contract';
+/**
+ * What the tool's `entitlements` slot returns (the billing rail spec, §7 and
+ * §8b): the three lists `GET /instance` shows (the priced actions with their
+ * default credits, the limits and the features per tier) plus the route
+ * declarations the gate enforces. A function of the environment, so an oss
+ * value can be the operator's env cap.
+ */
+export interface ToolEntitlementDeclaration extends ToolEntitlements {
+    routes: RouteEntitlementDeclarations;
+}
+/** A tool that declares nothing: no route is gated, discovery shows empty lists. */
+export declare const EMPTY_TOOL_ENTITLEMENTS: ToolEntitlementDeclaration;
+/**
+ * The boot-time guard of the slot: every key a route declares must be
+ * declared with its values, and a metered route's unit must be the action's.
+ * A route that meters an action the price book does not know, or a limit no
+ * tier has a value for, is a declaration that could never be enforced or
+ * priced — it stops the boot, naming the route.
+ *
+ * Two checks run on the three lists themselves. First, they are parsed
+ * through the contract's `toolEntitlementsSchema`: a limit key missing a
+ * tier would otherwise resolve as unlimited in `profiles.ts` while
+ * `requiredPlanFor` reports no plan for it, so a malformed declaration stops
+ * the boot naming the first issue's path. Second, the ceiling: a limit whose
+ * `oss` value is a number is the operator's own ceiling, the instance's hard
+ * cap, and no tier may advertise more (nor `null`, unlimited) under it.
+ * Discovery once advertised a paid tier the handlers' mid-stream cap could
+ * never serve (PRDCT-2653); the boot now refuses the advertisement. A limit
+ * whose `oss` is `null` has no ceiling.
+ */
+export declare function assertToolEntitlements(decl: ToolEntitlementDeclaration): void;
+//# sourceMappingURL=slot.d.ts.map

package/dist/entitlements/slot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot.d.ts","sourceRoot":"","sources":["../../src/entitlements/slot.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,4BAA4B,EACjC,KAAK,gBAAgB,EACtB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAClE,MAAM,EAAE,4BAA4B,CAAC;CACtC;AAED,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,EAAE,0BAKrC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,0BAA0B,GAAG,IAAI,CA0D7E"}

package/dist/entitlements/slot.js

@@ -0,0 +1,75 @@
+import { declareRouteEntitlements, ENTITLEMENT_TIERS, featureKeyOf, toolEntitlementsSchema } from '@antasphere/chassis-contract';
+/** A tool that declares nothing: no route is gated, discovery shows empty lists. */
+export const EMPTY_TOOL_ENTITLEMENTS = {
+    actions: [],
+    limits: {},
+    features: {},
+    routes: declareRouteEntitlements([])
+};
+/**
+ * The boot-time guard of the slot: every key a route declares must be
+ * declared with its values, and a metered route's unit must be the action's.
+ * A route that meters an action the price book does not know, or a limit no
+ * tier has a value for, is a declaration that could never be enforced or
+ * priced — it stops the boot, naming the route.
+ *
+ * Two checks run on the three lists themselves. First, they are parsed
+ * through the contract's `toolEntitlementsSchema`: a limit key missing a
+ * tier would otherwise resolve as unlimited in `profiles.ts` while
+ * `requiredPlanFor` reports no plan for it, so a malformed declaration stops
+ * the boot naming the first issue's path. Second, the ceiling: a limit whose
+ * `oss` value is a number is the operator's own ceiling, the instance's hard
+ * cap, and no tier may advertise more (nor `null`, unlimited) under it.
+ * Discovery once advertised a paid tier the handlers' mid-stream cap could
+ * never serve (PRDCT-2653); the boot now refuses the advertisement. A limit
+ * whose `oss` is `null` has no ceiling.
+ */
+export function assertToolEntitlements(decl) {
+    const parsed = toolEntitlementsSchema.safeParse({
+        actions: decl.actions,
+        limits: decl.limits,
+        features: decl.features
+    });
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const path = issue ? issue.path.map((p) => String(p)).join('.') : '';
+        throw new Error(`tool definition: entitlements declaration is malformed: ${path}: ${issue?.message ?? 'invalid'}`);
+    }
+    for (const [key, limit] of Object.entries(decl.limits)) {
+        const ceiling = limit.oss;
+        if (typeof ceiling !== 'number')
+            continue;
+        for (const tier of ENTITLEMENT_TIERS) {
+            const value = limit[tier];
+            if (typeof value !== 'number' || value > ceiling) {
+                throw new Error(`tool definition: entitlements.limits.${key}.${tier} (${String(value)}) is above the instance ceiling (oss ${ceiling}): a plan value the instance cannot serve must not be advertised`);
+            }
+        }
+    }
+    const actions = new Map(decl.actions.map((a) => [a.key, a]));
+    const seenActions = new Set();
+    for (const a of decl.actions) {
+        if (seenActions.has(a.key))
+            throw new Error(`tool definition: entitlements.actions declares ${a.key} twice`);
+        seenActions.add(a.key);
+    }
+    for (const [key, entry] of decl.routes) {
+        if (entry.meter) {
+            const action = actions.get(entry.meter.key);
+            if (!action) {
+                throw new Error(`tool definition: route ${key} meters "${entry.meter.key}", which entitlements.actions does not declare`);
+            }
+            if (action.unit !== entry.meter.unit) {
+                throw new Error(`tool definition: route ${key} meters "${entry.meter.key}" in ${entry.meter.unit}, the action is priced per ${action.unit}`);
+            }
+        }
+        if (entry.limit && !(entry.limit.key in decl.limits)) {
+            throw new Error(`tool definition: route ${key} checks the limit "${entry.limit.key}", which entitlements.limits does not declare`);
+        }
+        const feature = featureKeyOf(entry);
+        if (feature && !(feature in decl.features)) {
+            throw new Error(`tool definition: route ${key} needs the feature "${feature}", which entitlements.features does not declare`);
+        }
+    }
+}
+//# sourceMappingURL=slot.js.map

package/dist/entitlements/slot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot.js","sourceRoot":"","sources":["../../src/entitlements/slot.ts"],"names":[],"mappings":"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"}