@voltro/plugin-licensing 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+import { Effect } from 'effect';
+import { Tag } from 'effect/Context';
+import { VoidIfEmpty } from 'effect/Types';
+import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+/** A numeric cap, or `'unlimited'` for no cap. */
+export declare type EntitlementLimit = number | 'unlimited';
+
+export declare const entitlementResolver: (tenantId: string | null | undefined, key: string) => Effect.Effect<number | null>;
+
+/** Whether the current license grants `plugin` (name without the
+ *  `@voltro/plugin-` prefix) for production use. Reads the in-memory snapshot;
+ *  no license / no grant → false (fail-closed). */
+export declare const licenseAllowsPlugin: (plugin: string) => boolean;
+
+/** The entitlement + feature grant a license carries. */
+export declare interface LicenseClaims {
+    /** If set, the license applies ONLY to this tenant id; unset = deployment-wide. */
+    readonly tenant?: string;
+    /** Edition label (e.g. `'pro'`, `'enterprise'`). */
+    readonly edition: string;
+    /** Per-key numeric limits. */
+    readonly entitlements: Readonly<Record<string, EntitlementLimit>>;
+    /** Boolean feature flags granted. */
+    readonly features: ReadonlyArray<string>;
+    /** Plugins licensed for production use (the "installed ≠ billable" gate —
+     *  a plugin can be present in the bundle but only run under a license grant).
+     *  Names without the `@voltro/plugin-` prefix, e.g. `['storage','search']`. */
+    readonly plugins: ReadonlyArray<string>;
+    /** Unix-seconds expiry (from the JWT `exp`). */
+    readonly exp: number;
+    /** Unix-seconds issued-at (from the JWT `iat`), if present. */
+    readonly iat?: number;
+    /** Key id from the JWS header — supports public-key rotation. */
+    readonly kid?: string;
+}
+
+export declare const LicenseService: Tag<LicenseServiceShape, LicenseServiceShape>;
+
+/** The service handlers can `yield*` to read the current license directly (for
+ *  feature checks beyond billing's metered entitlements). */
+export declare interface LicenseServiceShape {
+    readonly snapshot: () => LicenseSnapshot | undefined;
+    readonly limitFor: (tenantId: string | null | undefined, key: string) => number | undefined;
+    readonly hasFeature: (feature: string) => boolean;
+    readonly allowsPlugin: (plugin: string) => boolean;
+    readonly edition: () => string | undefined;
+}
+
+export declare interface LicenseSnapshot {
+    readonly claims: LicenseClaims;
+    /**
+     * Numeric limit for a `(tenant, key)` pair: a finite cap, `Infinity` for an
+     * `'unlimited'` entitlement, or `undefined` when this license doesn't cover
+     * the key (or is scoped to a different tenant) — the caller then falls back to
+     * its own defaults (billing's static plan registry).
+     */
+    readonly limitFor: (tenantId: string | null | undefined, key: string) => number | undefined;
+    /** Whether a boolean feature is granted by the license. */
+    readonly hasFeature: (feature: string) => boolean;
+    /** Whether a plugin is licensed for production use (name without the
+     *  `@voltro/plugin-` prefix, e.g. `'storage'`). The "installed ≠ billable" gate. */
+    readonly allowsPlugin: (plugin: string) => boolean;
+}
+
+export declare class LicenseVerifyError extends LicenseVerifyError_base<{
+    /** `expired` — past `exp`; `invalid` — bad signature; `key` — unusable public
+     *  key; `malformed` — verified but the payload isn't a license. */
+    readonly reason: 'expired' | 'invalid' | 'key' | 'malformed';
+    readonly message: string;
+}> {
+}
+
+declare const LicenseVerifyError_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "LicenseVerifyError";
+} & Readonly<A>;
+
+export declare const licensingPlugin: (options?: LicensingPluginOptions) => VoltroPlugin;
+
+export declare interface LicensingPluginOptions {
+    /** Ed25519 public key (SPKI/PEM) that verifies the license. Falls back to
+     *  `VOLTRO_LICENSE_PUBLIC_KEY`. Safe to embed — it is a PUBLIC key. */
+    readonly publicKey?: string;
+    /** The signed license token. Falls back to `VOLTRO_LICENSE_KEY`. */
+    readonly licenseKey?: string;
+    /** URL to periodically re-fetch a fresh signed license (entitlement sync).
+     *  With `refreshMs`, a cluster-coordinated refresh re-verifies + re-installs
+     *  the snapshot. (The cloud endpoint that serves it ships in a later milestone.) */
+    readonly snapshotUrl?: string;
+    /** Refresh interval (ms) for `snapshotUrl`. Default 15 minutes. */
+    readonly refreshMs?: number;
+    /** Seconds an expired license is still honored (grace) before it goes dark.
+     *  Default 0. */
+    readonly graceSeconds?: number;
+    /** Alias suffix when running more than one instance. */
+    readonly name?: string;
+}
+
+/** Thrown when a plugin's production use requires a license grant the current
+ *  license doesn't carry (the "installed ≠ billable" gate). */
+export declare class PluginNotLicensed extends PluginNotLicensed_base<{
+    readonly plugin: string;
+}> {
+}
+
+declare const PluginNotLicensed_base: new <A extends Record<string, any> = {}>(args: VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => YieldableError & {
+    readonly _tag: "PluginNotLicensed";
+} & Readonly<A>;
+
+/** Gate a handler (or a plugin interceptor) on a plugin being licensed. Fails
+ *  `PluginNotLicensed` when it isn't. */
+export declare const requireLicensedPlugin: (plugin: string) => Effect.Effect<void, PluginNotLicensed>;
+
+/**
+ * Verify a license token against an Ed25519 public key (SPKI/PEM), OFFLINE.
+ * Returns the decoded {@link LicenseClaims} or a typed {@link LicenseVerifyError}
+ * (expiry is enforced by `jose`). No network access.
+ */
+export declare const verifyLicense: (token: string, publicKeyPem: string) => Effect.Effect<LicenseClaims, LicenseVerifyError>;
+
+export { }

package/dist/index.js

@@ -0,0 +1,135 @@
+import { Data as e, Effect as t } from "effect";
+import { definePlugin as n, definePluginService as r } from "@voltro/protocol";
+import { pluginEnv as i } from "@voltro/env";
+import { importSPKI as a, jwtVerify as o } from "jose";
+//#region src/verify.ts
+var s = class extends e.TaggedError("LicenseVerifyError") {}, c = (e) => typeof e == "object" && e && "code" in e ? String(e.code) : "", l = (e) => {
+	let t = e instanceof Error ? e.message : String(e);
+	return c(e) === "ERR_JWT_EXPIRED" ? new s({
+		reason: "expired",
+		message: t
+	}) : new s({
+		reason: "invalid",
+		message: t
+	});
+}, u = (e) => e === "unlimited" || typeof e == "number" && Number.isFinite(e) && e >= 0, d = (e, n) => {
+	let r = e.edition, i = e.entitlements, a = e.features;
+	if (typeof r != "string" || typeof i != "object" || !i) return t.fail(new s({
+		reason: "malformed",
+		message: "missing edition/entitlements"
+	}));
+	let o = {};
+	for (let [e, n] of Object.entries(i)) {
+		if (!u(n)) return t.fail(new s({
+			reason: "malformed",
+			message: `bad entitlement '${e}'`
+		}));
+		o[e] = n;
+	}
+	let c = Array.isArray(a) ? a.filter((e) => typeof e == "string") : [], l = e.plugins, d = Array.isArray(l) ? l.filter((e) => typeof e == "string") : [];
+	return t.succeed({
+		...typeof e.tenant == "string" ? { tenant: e.tenant } : {},
+		edition: r,
+		entitlements: o,
+		features: c,
+		plugins: d,
+		exp: typeof e.exp == "number" ? e.exp : 0,
+		...typeof e.iat == "number" ? { iat: e.iat } : {},
+		...n === void 0 ? {} : { kid: n }
+	});
+}, f = (e, n) => t.tryPromise({
+	try: () => a(n, "EdDSA"),
+	catch: (e) => new s({
+		reason: "key",
+		message: e instanceof Error ? e.message : String(e)
+	})
+}).pipe(t.flatMap((n) => t.tryPromise({
+	try: async () => {
+		let { payload: t, protectedHeader: r } = await o(e, n, { algorithms: ["EdDSA"] });
+		return {
+			payload: t,
+			kid: r.kid
+		};
+	},
+	catch: l
+})), t.flatMap(({ payload: e, kid: t }) => d(e, t))), p = (e, t = {}) => {
+	let n = new Set(e.features), r = new Set(e.plugins), i = t.graceSeconds ?? 0, a = t.now ?? (() => Date.now() / 1e3), o = () => e.exp <= 0 || a() <= e.exp + i;
+	return {
+		claims: e,
+		limitFor: (t, n) => {
+			if (!o() || e.tenant !== void 0 && e.tenant !== t) return;
+			let r = e.entitlements[n];
+			if (r !== void 0) return r === "unlimited" ? Infinity : r;
+		},
+		hasFeature: (e) => o() && n.has(e),
+		allowsPlugin: (e) => o() && r.has(e)
+	};
+}, m, h = (e) => {
+	m = e;
+}, g = () => m, _ = (e, n) => t.sync(() => {
+	let t = g()?.limitFor(e, n);
+	return t === void 0 ? null : t;
+}), v = i([{
+	name: "VOLTRO_LICENSE_PUBLIC_KEY",
+	required: !1,
+	secret: !1,
+	description: "Ed25519 public key (SPKI/PEM) that verifies license keys offline."
+}, {
+	name: "VOLTRO_LICENSE_KEY",
+	required: !1,
+	secret: !1,
+	description: "The signed EdDSA license token, verified offline at boot."
+}]), { Tag: y, Live: b } = r("@voltro/plugin-licensing/LicenseService", {
+	snapshot: () => g(),
+	limitFor: (e, t) => g()?.limitFor(e, t),
+	hasFeature: (e) => g()?.hasFeature(e) ?? !1,
+	allowsPlugin: (e) => g()?.allowsPlugin(e) ?? !1,
+	edition: () => g()?.claims.edition
+}), x = class extends e.TaggedError("PluginNotLicensed") {}, S = (e) => g()?.allowsPlugin(e) ?? !1, C = (e) => S(e) ? t.void : t.fail(new x({ plugin: e })), w = (e = {}) => {
+	let r = v.read("VOLTRO_LICENSE_PUBLIC_KEY", e.publicKey), i = v.read("VOLTRO_LICENSE_KEY", e.licenseKey), a = e.graceSeconds ?? 0, o = e.refreshMs ?? 15 * 6e4, s, c = (e, n) => f(e, n).pipe(t.match({
+		onSuccess: (e) => {
+			h(p(e, { graceSeconds: a })), s?.info("license active", {
+				edition: e.edition,
+				entitlements: Object.keys(e.entitlements).length,
+				exp: e.exp
+			});
+		},
+		onFailure: (e) => {
+			s?.warn("license verification failed — entitlements fall back to static plan", {
+				reason: e.reason,
+				message: e.message
+			});
+		}
+	}));
+	return n({
+		name: e.name ? `@voltro/plugin-licensing#${e.name}` : "@voltro/plugin-licensing",
+		description: "Offline-verified EdDSA license keys + entitlement snapshots; feeds @voltro/plugin-billing via entitlementResolver.",
+		declaredEnv: v.declared,
+		services: b,
+		onActivate: (e) => t.gen(function* () {
+			if (s = e.logger, r === void 0 || i === void 0) {
+				e.logger.debug("licensing: no license configured — static plan entitlements apply");
+				return;
+			}
+			yield* c(i, r);
+		}),
+		bindDataStore: (n, i) => {
+			let a = e.snapshotUrl;
+			if (a === void 0 || r === void 0 || i?.scheduleCoordinated === void 0) return;
+			let l = r;
+			i.scheduleCoordinated("licensing.refresh", o, async () => {
+				try {
+					let e = await fetch(a);
+					if (!e.ok) return;
+					let n = (await e.text()).trim();
+					n.length > 0 && await t.runPromise(c(n, l));
+				} catch (e) {
+					s?.warn("license refresh failed", { message: e instanceof Error ? e.message : String(e) });
+				}
+			});
+		},
+		onDeactivate: () => t.sync(() => h(void 0))
+	});
+};
+//#endregion
+export { y as LicenseService, s as LicenseVerifyError, x as PluginNotLicensed, _ as entitlementResolver, S as licenseAllowsPlugin, w as licensingPlugin, C as requireLicensedPlugin, f as verifyLicense };

package/dist/sign.d.ts

@@ -0,0 +1,29 @@
+/** A numeric cap, or `'unlimited'` for no cap. */
+declare type EntitlementLimit = number | 'unlimited';
+
+/**
+ * Sign a license token with an Ed25519 private key (PKCS8/PEM). Returns a compact
+ * EdDSA JWT that {@link verifyLicense} checks offline. `nowSeconds` is injectable
+ * for deterministic tests.
+ */
+export declare const signLicense: (input: SignLicenseInput, privateKeyPem: string, nowSeconds?: number) => Promise<string>;
+
+export declare interface SignLicenseInput {
+    /** Scope the license to one tenant id; omit for a deployment-wide license. */
+    readonly tenant?: string;
+    /** Edition label (e.g. `'pro'`, `'enterprise'`). */
+    readonly edition: string;
+    /** Per-key numeric limits (`'unlimited'` for no cap). */
+    readonly entitlements: Readonly<Record<string, EntitlementLimit>>;
+    /** Boolean feature flags to grant. */
+    readonly features?: ReadonlyArray<string>;
+    /** Plugins licensed for production use (names without the
+     *  `@voltro/plugin-` prefix, e.g. `['storage']`). */
+    readonly plugins?: ReadonlyArray<string>;
+    /** Seconds from `now` until the license expires. */
+    readonly ttlSeconds: number;
+    /** Key id stamped into the JWS header (public-key rotation). */
+    readonly kid?: string;
+}
+
+export { }

package/dist/sign.js

@@ -0,0 +1,17 @@
+import { SignJWT as e, importPKCS8 as t } from "jose";
+//#region src/sign.ts
+var n = async (n, r, i) => {
+	let a = await t(r, "EdDSA"), o = i ?? Math.floor(Date.now() / 1e3);
+	return new e({
+		...n.tenant === void 0 ? {} : { tenant: n.tenant },
+		edition: n.edition,
+		entitlements: n.entitlements,
+		features: n.features ?? [],
+		plugins: n.plugins ?? []
+	}).setProtectedHeader({
+		alg: "EdDSA",
+		...n.kid === void 0 ? {} : { kid: n.kid }
+	}).setIssuedAt(o).setExpirationTime(o + n.ttlSeconds).sign(a);
+};
+//#endregion
+export { n as signLicense };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@voltro/plugin-licensing",
+  "version": "0.1.0",
+  "description": "Offline-verified license keys + cloud-issued entitlement snapshots for @voltro apps",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./sign": {
+      "types": "./dist/sign.d.ts",
+      "import": "./dist/sign.js",
+      "default": "./dist/sign.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/logger": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "jose": "^6.2.3"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}