@nexus-mindgarden/plugin-license-foundation 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Pajor
+
+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

@@ -0,0 +1,63 @@
+# @nexus-mindgarden/plugin-license-foundation
+
+NEXUS plugin-entitlement **LicenseGate** for the host's `PluginManager.activate` seam — offline-first, default-deny, last-known-good grace, plus the entitle-on-activation call.
+
+## Model
+
+NEXUS issues plugin entitlements as **signed claims on the agent-JWT** (`plugins: string[]`, `ent_ver: int`), verifiable **offline via JWKS**. The host already verifies this JWT for app-licensing; this package adds the per-plugin gate. Revocation = `ent_ver` bump + SSE → host reconcile. (Wire: chatbus `#plugin-licensing`, nexus #5374 / agent #5377.)
+
+## Quick use
+
+```ts
+import {
+  createLicenseClient,
+  verifyEntitlementJwt,
+  remoteJwks,
+  entitlePlugin,
+} from '@nexus-mindgarden/plugin-license-foundation'
+
+// Cache the JWKS getter once (don't re-fetch per verify).
+const jwks = remoteJwks('https://nexus.example/api/licenses/jwks.json')
+
+const { gate } = createLicenseClient({
+  // Yield the current entitlement — from the host's already-verified agent-JWT
+  // claims, or by verifying the raw JWT here:
+  resolveEntitlement: async () => {
+    const jwt = await host.currentAgentJwt() // host-supplied
+    if (!jwt) return null
+    return verifyEntitlementJwt(jwt, {
+      jwks,
+      issuer: 'nexus.digitaleprojekte.at',
+      audience: 'nexus',
+    })
+  },
+  graceMs: 7 * 24 * 60 * 60 * 1000, // last-known-good offline window (host policy)
+  // failOpen: true,                // ONLY for dev / enforce_entitlements=false
+})
+
+// Drops into PluginManager.activate's LicenseGate.check seam:
+const result = await gate.check({ pluginId: 'apex-2d', userId })
+// → { ok: true } | { ok: false, reason: 'not_entitled' | 'no_entitlement' | 'stale_entitlement' | … }
+```
+
+### Entitle on activation (free → grant, paid → 402)
+
+```ts
+const r = await entitlePlugin({
+  endpoint: 'https://nexus.example/api/licenses/entitlements/plugin',
+  slug: 'apex-2d',
+  activationToken, // device credential (Bearer)
+})
+// free  → { ok: true }
+// paid  → { ok: false, reason: 'purchase_required' }
+```
+
+## Security
+
+- **Default-deny:** no resolvable entitlement and no usable cache → `{ ok: false }`. `failOpen` is opt-in (dev / issuance-before-enforcement).
+- **Alg-pinned:** `verifyEntitlementJwt` accepts **only** `EdDSA` — never `HS*`/`none`. Any verify failure throws (no permissive path).
+- **Offline grace** is bounded by the cached `exp` + `graceMs` (host policy); past it → `stale_entitlement`, not a silent allow. `verifyEntitlementJwt` **requires** `exp` (an exp-less token → `invalid_claims`), so a verified entitlement's grace is always anchored on a signed freshness boundary. (A custom `resolveEntitlement` that yields an `exp`-less object anchors grace on last-resolved-online instead.)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import type { Entitlement, LicenseGate } from './types.js';
+export interface CreateLicenseClientOptions {
+    /**
+     * Yields the current entitlement, or `null` when none is available (e.g.
+     * offline and no token yet). May be sync or async. On `null`/throw the gate
+     * falls back to last-known-good within the grace window.
+     */
+    resolveEntitlement: () => Promise<Entitlement | null> | Entitlement | null;
+    /**
+     * Last-known-good offline grace (ms past the cached entitlement's `exp`). When
+     * `resolveEntitlement` can't produce a fresh entitlement, a cached one is
+     * trusted until `exp + graceMs`. Default `0` (no grace → only fresh claims pass).
+     * Host-policy — NEXUS sends `exp` (short TTL), not a grace window.
+     */
+    graceMs?: number;
+    /**
+     * When true, a gate that cannot resolve an entitlement AND has no usable cache
+     * returns `{ ok: true }` instead of denying. Default `false` (DEFAULT-DENY).
+     * Use only for dev / `enforce_entitlements=false` (issuance-before-enforcement).
+     */
+    failOpen?: boolean;
+    /** Clock (ms epoch). Default `Date.now`. Injectable for tests. */
+    now?: () => number;
+}
+export interface LicenseClient {
+    gate: LicenseGate;
+    /** The cached last-known-good entitlement (for diagnostics / ent_ver reconcile). */
+    lastKnownGood(): Entitlement | null;
+}
+export declare function createLicenseClient(opts: CreateLicenseClientOptions): LicenseClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAqB,MAAM,YAAY,CAAA;AAE7E,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,kBAAkB,EAAE,MAAM,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,WAAW,GAAG,IAAI,CAAA;IAC1E;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAA;IACjB,oFAAoF;IACpF,aAAa,IAAI,WAAW,GAAG,IAAI,CAAA;CACpC;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,GAAG,aAAa,CA8DnF"}

package/dist/client.js

@@ -0,0 +1,67 @@
+// createLicenseClient — produces a LicenseGate for the host's PluginManager.activate
+// seam. Offline-first (consumes verified entitlement claims; no online call on the
+// hot path), default-deny, with a host-policy last-known-good grace window.
+//
+// The host wires `resolveEntitlement` to yield the current entitlement — either
+// from its already-verified NEXUS agent-JWT claims, or via verifyEntitlementJwt
+// (this package) against JWKS. Revocation (ent_ver bump + SSE) is the host's
+// reconcile job; this gate just answers "is this plugin entitled, right now?".
+export function createLicenseClient(opts) {
+    const graceMs = opts.graceMs ?? 0;
+    const failOpen = opts.failOpen ?? false;
+    const now = opts.now ?? Date.now;
+    let cache = null;
+    /** End of the trust window for a cached entitlement (ms epoch). */
+    function trustUntil(c) {
+        const base = c.entitlement.exp !== undefined ? c.entitlement.exp * 1000 : c.cachedAt;
+        return base + graceMs;
+    }
+    function decide(entitlement, pluginId) {
+        return entitlement.plugins.includes(pluginId)
+            ? { ok: true }
+            : { ok: false, reason: 'not_entitled', message: `plugin '${pluginId}' not in entitlement` };
+    }
+    const gate = {
+        async check(input) {
+            let fresh = null;
+            let threw = false;
+            try {
+                fresh = await opts.resolveEntitlement();
+            }
+            catch {
+                threw = true;
+            }
+            // Online path: a freshly-resolved entitlement is authoritative + cached.
+            if (fresh) {
+                cache = { entitlement: fresh, cachedAt: now() };
+                return decide(fresh, input.pluginId);
+            }
+            // Offline path: fall back to last-known-good within the grace window.
+            if (cache) {
+                if (now() <= trustUntil(cache)) {
+                    return decide(cache.entitlement, input.pluginId);
+                }
+                // cache exists but is past exp + grace
+                if (failOpen)
+                    return { ok: true };
+                return {
+                    ok: false,
+                    reason: 'stale_entitlement',
+                    message: 'cached entitlement past exp + grace window',
+                };
+            }
+            // No fresh entitlement and no cache at all.
+            if (failOpen)
+                return { ok: true };
+            return {
+                ok: false,
+                reason: threw ? 'entitlement_error' : 'no_entitlement',
+                message: threw
+                    ? 'resolveEntitlement threw and no cache available'
+                    : 'no entitlement available',
+            };
+        },
+    };
+    return { gate, lastKnownGood: () => cache?.entitlement ?? null };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,mFAAmF;AACnF,4EAA4E;AAC5E,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,+EAA+E;AAkC/E,MAAM,UAAU,mBAAmB,CAAC,IAAgC;IAClE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAA;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAA;IACvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAA;IAEhC,IAAI,KAAK,GAA0D,IAAI,CAAA;IAEvE,mEAAmE;IACnE,SAAS,UAAU,CAAC,CAAiD;QACnE,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;QACpF,OAAO,IAAI,GAAG,OAAO,CAAA;IACvB,CAAC;IAED,SAAS,MAAM,CAAC,WAAwB,EAAE,QAAgB;QACxD,OAAO,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAC3C,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE;YACd,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,QAAQ,sBAAsB,EAAE,CAAA;IAC/F,CAAC;IAED,MAAM,IAAI,GAAgB;QACxB,KAAK,CAAC,KAAK,CAAC,KAAK;YACf,IAAI,KAAK,GAAuB,IAAI,CAAA;YACpC,IAAI,KAAK,GAAG,KAAK,CAAA;YACjB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAA;YACzC,CAAC;YAAC,MAAM,CAAC;gBACP,KAAK,GAAG,IAAI,CAAA;YACd,CAAC;YAED,yEAAyE;YACzE,IAAI,KAAK,EAAE,CAAC;gBACV,KAAK,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,CAAA;gBAC/C,OAAO,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;YACtC,CAAC;YAED,sEAAsE;YACtE,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,GAAG,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC/B,OAAO,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;gBAClD,CAAC;gBACD,uCAAuC;gBACvC,IAAI,QAAQ;oBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;gBACjC,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,MAAM,EAAE,mBAAmB;oBAC3B,OAAO,EAAE,4CAA4C;iBACtD,CAAA;YACH,CAAC;YAED,4CAA4C;YAC5C,IAAI,QAAQ;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;YACjC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,gBAAgB;gBACtD,OAAO,EAAE,KAAK;oBACZ,CAAC,CAAC,iDAAiD;oBACnD,CAAC,CAAC,0BAA0B;aAC/B,CAAA;QACH,CAAC;KACF,CAAA;IAED,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,WAAW,IAAI,IAAI,EAAE,CAAA;AAClE,CAAC"}

package/dist/entitle.d.ts

@@ -0,0 +1,23 @@
+import type { LicenseGateResult } from './types.js';
+export interface EntitlePluginOptions {
+    /** Full entitle endpoint, e.g. `https://nexus.example/api/licenses/entitlements/plugin`. */
+    endpoint: string;
+    /** Plugin slug to entitle (the NEXUS-canonical slug, e.g. `apex-2d`). */
+    slug: string;
+    /** Device activation-token (Bearer) — the same credential used for getEntitlements. */
+    activationToken: string;
+    /** Optional fetch override (tests / custom agent). Default global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Entitle a plugin on activation. Returns:
+ *  - `{ ok: true }` on grant (free auto-grant, 2xx).
+ *  - `{ ok: false, reason: 'purchase_required' }` on 402 (paid, not purchased) —
+ *    deterministically mapped from `detail.reason === 'purchase_required'`.
+ *  - `{ ok: false, reason: 'entitlement_error', message }` on any other failure.
+ *
+ * Never throws — always returns a LicenseGateResult (the activation seam wants a
+ * decision, not an exception).
+ */
+export declare function entitlePlugin(opts: EntitlePluginOptions): Promise<LicenseGateResult>;
+//# sourceMappingURL=entitle.d.ts.map

package/dist/entitle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitle.d.ts","sourceRoot":"","sources":["../src/entitle.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,QAAQ,EAAE,MAAM,CAAA;IAChB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,uFAAuF;IACvF,eAAe,EAAE,MAAM,CAAA;IACvB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA6C1F"}

package/dist/entitle.js

@@ -0,0 +1,64 @@
+// Entitle-on-activation — the optional online step at plugin activation.
+//
+// `POST /api/licenses/entitlements/plugin { plugin_slug }` (Bearer=activation_token),
+// idempotent. Free plugins → auto-grant (2xx). Paid plugins → 402 with
+// `{ detail: { reason: 'purchase_required', … } }` (until shop-checkout exists).
+// After a successful grant, the host refreshes entitlements (cache + SSE handle
+// the rest) so the LicenseGate sees the new slug.
+/**
+ * Entitle a plugin on activation. Returns:
+ *  - `{ ok: true }` on grant (free auto-grant, 2xx).
+ *  - `{ ok: false, reason: 'purchase_required' }` on 402 (paid, not purchased) —
+ *    deterministically mapped from `detail.reason === 'purchase_required'`.
+ *  - `{ ok: false, reason: 'entitlement_error', message }` on any other failure.
+ *
+ * Never throws — always returns a LicenseGateResult (the activation seam wants a
+ * decision, not an exception).
+ */
+export async function entitlePlugin(opts) {
+    const fetchFn = opts.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await fetchFn(opts.endpoint, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${opts.activationToken}`,
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            body: JSON.stringify({ plugin_slug: opts.slug }),
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: 'entitlement_error',
+            message: `entitle fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (res.ok)
+        return { ok: true };
+    if (res.status === 402) {
+        // Deterministic shape (nexus): { detail: { reason: 'purchase_required', message } }
+        let reasonField;
+        let message;
+        try {
+            const body = (await res.json());
+            reasonField = body?.detail?.reason;
+            message = typeof body?.detail?.message === 'string' ? body.detail.message : undefined;
+        }
+        catch {
+            // ignore parse error — treat as purchase_required by status anyway
+        }
+        if (reasonField === 'purchase_required' || reasonField === undefined) {
+            return { ok: false, reason: 'purchase_required', ...(message ? { message } : {}) };
+        }
+        return {
+            ok: false,
+            reason: 'entitlement_error',
+            message: `402 with reason '${String(reasonField)}'`,
+        };
+    }
+    return { ok: false, reason: 'entitlement_error', message: `entitle returned HTTP ${res.status}` };
+}
+//# sourceMappingURL=entitle.js.map

package/dist/entitle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitle.js","sourceRoot":"","sources":["../src/entitle.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,sFAAsF;AACtF,uEAAuE;AACvE,iFAAiF;AACjF,gFAAgF;AAChF,kDAAkD;AAelD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAA0B;IAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAA;IACvC,IAAI,GAAa,CAAA;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE;YACjC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,IAAI,CAAC,eAAe,EAAE;gBAC/C,cAAc,EAAE,kBAAkB;gBAClC,MAAM,EAAE,kBAAkB;aAC3B;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;SACjD,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,mBAAmB;YAC3B,OAAO,EAAE,yBAAyB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;SACrF,CAAA;IACH,CAAC;IAED,IAAI,GAAG,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;IAE/B,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACvB,oFAAoF;QACpF,IAAI,WAAoB,CAAA;QACxB,IAAI,OAA2B,CAAA;QAC/B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAyD,CAAA;YACvF,WAAW,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAA;YAClC,OAAO,GAAG,OAAO,IAAI,EAAE,MAAM,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;QACvF,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;QACrE,CAAC;QACD,IAAI,WAAW,KAAK,mBAAmB,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YACrE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;QACpF,CAAC;QACD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,mBAAmB;YAC3B,OAAO,EAAE,oBAAoB,MAAM,CAAC,WAAW,CAAC,GAAG;SACpD,CAAA;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,yBAAyB,GAAG,CAAC,MAAM,EAAE,EAAE,CAAA;AACnG,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createLicenseClient, type CreateLicenseClientOptions, type LicenseClient, } from './client.js';
+export { verifyEntitlementJwt, remoteJwks, LicenseVerifyError, type VerifyEntitlementJwtOptions, } from './jwks.js';
+export { entitlePlugin, type EntitlePluginOptions } from './entitle.js';
+export { EntitlementSchema, type Entitlement, type LicenseGate, type LicenseGateResult, type LicenseDenyReason, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,aAAa,GACnB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,kBAAkB,EAClB,KAAK,2BAA2B,GACjC,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACvE,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// @nexus-mindgarden/plugin-license-foundation — NEXUS entitlement LicenseGate.
+//
+// Drops into the host's PluginManager.activate seam (`LicenseGate.check`). The
+// host already verifies the NEXUS agent-JWT for app-licensing; this package adds
+// the per-plugin gate (offline, default-deny, last-known-good grace) + the
+// entitle-on-activation call. Wire-spec: chatbus #plugin-licensing (nexus #5374,
+// agent #5377). The `checkLicense` stub in HOST-INTEGRATION-GUIDE §2.3 becomes real.
+export { createLicenseClient, } from './client.js';
+export { verifyEntitlementJwt, remoteJwks, LicenseVerifyError, } from './jwks.js';
+export { entitlePlugin } from './entitle.js';
+export { EntitlementSchema, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,+EAA+E;AAC/E,iFAAiF;AACjF,2EAA2E;AAC3E,iFAAiF;AACjF,qFAAqF;AAErF,OAAO,EACL,mBAAmB,GAGpB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,kBAAkB,GAEnB,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,aAAa,EAA6B,MAAM,cAAc,CAAA;AACvE,OAAO,EACL,iBAAiB,GAKlB,MAAM,YAAY,CAAA"}

package/dist/jwks.d.ts

@@ -0,0 +1,26 @@
+import { type JWTVerifyGetKey } from 'jose';
+import { type Entitlement } from './types.js';
+export declare class LicenseVerifyError extends Error {
+    readonly code: 'jwks_fetch_failed' | 'invalid_token' | 'expired' | 'invalid_claims';
+    constructor(code: 'jwks_fetch_failed' | 'invalid_token' | 'expired' | 'invalid_claims', message: string);
+}
+export interface VerifyEntitlementJwtOptions {
+    /** JWKS endpoint, e.g. `https://nexus.example/api/licenses/jwks.json`, OR a pre-built jose key-getter. */
+    jwks: string | JWTVerifyGetKey;
+    /** Expected `iss` (e.g. `nexus.digitaleprojekte.at`). Enforced if set. */
+    issuer?: string;
+    /** Expected `aud` (e.g. `nexus`). Enforced if set. */
+    audience?: string;
+}
+/** Build (and let the caller cache) a JWKS key-getter from a URL. */
+export declare function remoteJwks(jwksUrl: string): JWTVerifyGetKey;
+/**
+ * Verify a NEXUS agent-JWT against JWKS (alg-pinned EdDSA) and extract the
+ * entitlement claims. Throws LicenseVerifyError on any failure — there is no
+ * permissive return path (default-deny by construction).
+ *
+ * NOTE: pass a pre-built `remoteJwks(url)` getter (cached across calls) rather
+ * than a URL string in a hot path, so JWKS isn't re-fetched per verify.
+ */
+export declare function verifyEntitlementJwt(token: string, opts: VerifyEntitlementJwtOptions): Promise<Entitlement>;
+//# sourceMappingURL=jwks.d.ts.map

package/dist/jwks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../src/jwks.ts"],"names":[],"mappings":"AAQA,OAAO,EAAiC,KAAK,eAAe,EAAE,MAAM,MAAM,CAAA;AAC1E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAEhE,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,IAAI,EAAE,mBAAmB,GAAG,eAAe,GAAG,SAAS,GAAG,gBAAgB;gBAA1E,IAAI,EAAE,mBAAmB,GAAG,eAAe,GAAG,SAAS,GAAG,gBAAgB,EAC1F,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,2BAA2B;IAC1C,0GAA0G;IAC1G,IAAI,EAAE,MAAM,GAAG,eAAe,CAAA;IAC9B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,2BAA2B,GAChC,OAAO,CAAC,WAAW,CAAC,CA0CtB"}

package/dist/jwks.js

@@ -0,0 +1,68 @@
+// Offline JWKS verification of a NEXUS agent-JWT → Entitlement.
+//
+// The host typically already verifies the agent-JWT (for app-licensing) and can
+// pass the verified claims straight to createLicenseClient via resolveEntitlement.
+// This helper is for callers that hold the raw JWT and want the Foundation to do
+// the verify: alg-pinned EdDSA, JWKS-cached, optional iss/aud — default-deny by
+// construction (any verify failure throws, never returns a permissive result).
+import { jwtVerify, createRemoteJWKSet } from 'jose';
+import { EntitlementSchema } from './types.js';
+export class LicenseVerifyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'LicenseVerifyError';
+    }
+}
+/** Build (and let the caller cache) a JWKS key-getter from a URL. */
+export function remoteJwks(jwksUrl) {
+    return createRemoteJWKSet(new URL(jwksUrl));
+}
+/**
+ * Verify a NEXUS agent-JWT against JWKS (alg-pinned EdDSA) and extract the
+ * entitlement claims. Throws LicenseVerifyError on any failure — there is no
+ * permissive return path (default-deny by construction).
+ *
+ * NOTE: pass a pre-built `remoteJwks(url)` getter (cached across calls) rather
+ * than a URL string in a hot path, so JWKS isn't re-fetched per verify.
+ */
+export async function verifyEntitlementJwt(token, opts) {
+    const keyGetter = typeof opts.jwks === 'string' ? remoteJwks(opts.jwks) : opts.jwks;
+    let payload;
+    try {
+        const result = await jwtVerify(token, keyGetter, {
+            algorithms: ['EdDSA'], // alg-pinned: never accept HS*/none/etc.
+            ...(opts.issuer !== undefined ? { issuer: opts.issuer } : {}),
+            ...(opts.audience !== undefined ? { audience: opts.audience } : {}),
+        });
+        payload = result.payload;
+    }
+    catch (err) {
+        const e = err;
+        const msg = e.message ?? 'verify failed';
+        // Token-expiry first — most specific.
+        if (e.code === 'ERR_JWT_EXPIRED' || /expired/i.test(msg)) {
+            throw new LicenseVerifyError('expired', msg);
+        }
+        // JWKS unreachable / no key / timeout / transport — distinct from a bad token,
+        // so the host can retry-later instead of treating it as token-integrity.
+        if (e.code === 'ERR_JWKS_NO_MATCHING_KEY' ||
+            e.code === 'ERR_JWKS_TIMEOUT' ||
+            e.code === 'ERR_JWKS_MULTIPLE_MATCHING_KEYS' ||
+            /jwks|key set|fetch failed|timed out|network|ENOTFOUND|ECONNREFUSED/i.test(msg)) {
+            throw new LicenseVerifyError('jwks_fetch_failed', msg);
+        }
+        throw new LicenseVerifyError('invalid_token', msg);
+    }
+    const parsed = EntitlementSchema.safeParse(payload);
+    if (!parsed.success) {
+        throw new LicenseVerifyError('invalid_claims', `entitlement claims invalid: ${parsed.error.issues.map((i) => i.path.join('.')).join(', ')}`);
+    }
+    return {
+        plugins: parsed.data.plugins,
+        ent_ver: parsed.data.ent_ver,
+        ...(parsed.data.exp !== undefined ? { exp: parsed.data.exp } : {}),
+    };
+}
+//# sourceMappingURL=jwks.js.map

package/dist/jwks.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+/** Entitlement payload extracted from a verified NEXUS agent-JWT. */
+export interface Entitlement {
+    /** Entitled plugin slugs (the authoritative offline list mirror). */
+    plugins: string[];
+    /** Monotonic entitlements version (revocation / reconcile cursor). */
+    ent_ver: number;
+    /** JWT `exp` (unix seconds) — the claim's freshness boundary, if known. */
+    exp?: number;
+}
+/** Zod schema — parses the relevant claims off a verified JWT payload. Lenient
+ *  about extra claims (the agent-JWT carries more than just entitlements). */
+export declare const EntitlementSchema: z.ZodObject<{
+    plugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    ent_ver: z.ZodDefault<z.ZodNumber>;
+    exp: z.ZodNumber;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    plugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    ent_ver: z.ZodDefault<z.ZodNumber>;
+    exp: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    plugins: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    ent_ver: z.ZodDefault<z.ZodNumber>;
+    exp: z.ZodNumber;
+}, z.ZodTypeAny, "passthrough">>;
+/**
+ * Why a license check failed (or `undefined` on success):
+ *  - `not_entitled`       — entitlement resolved, plugin not in `plugins[]`.
+ *  - `no_entitlement`     — could not resolve an entitlement and no valid cache (default-deny).
+ *  - `stale_entitlement`  — only a cached entitlement exists and it is past `exp` + grace.
+ *  - `purchase_required`  — entitle-on-activation returned 402 (paid, not purchased).
+ *  - `entitlement_error`  — resolving/parsing the entitlement threw.
+ */
+export type LicenseDenyReason = 'not_entitled' | 'no_entitlement' | 'stale_entitlement' | 'purchase_required' | 'entitlement_error';
+export type LicenseGateResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: LicenseDenyReason;
+    message?: string;
+};
+/** The seam `@theseus/plugin-system` `PluginManager.activate` calls before activation. */
+export interface LicenseGate {
+    check(input: {
+        pluginId: string;
+        userId?: string;
+        manifest?: unknown;
+    }): Promise<LicenseGateResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;8EAC8E;AAC9E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;gCASd,CAAA;AAEhB;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,gBAAgB,GAChB,mBAAmB,GACnB,mBAAmB,GACnB,mBAAmB,CAAA;AAEvB,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9D,0FAA0F;AAC1F,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,KAAK,EAAE;QACX,QAAQ,EAAE,MAAM,CAAA;QAChB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,QAAQ,CAAC,EAAE,OAAO,CAAA;KACnB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;CAC/B"}

package/dist/types.js

@@ -0,0 +1,21 @@
+// Plugin-License Foundation — shared types for the NEXUS entitlement model.
+//
+// Entitlements ride as signed claims on the NEXUS agent-JWT (verified offline
+// via JWKS): `plugins: string[]` (entitled plugin slugs) + `ent_ver: int`
+// (monotonic version, bumped on revocation → host reconciles via SSE). The host
+// already verifies this JWT for app-licensing; this package adds the per-plugin
+// LicenseGate + last-known-good offline grace + the entitle-on-activation call.
+import { z } from 'zod';
+/** Zod schema — parses the relevant claims off a verified JWT payload. Lenient
+ *  about extra claims (the agent-JWT carries more than just entitlements). */
+export const EntitlementSchema = z
+    .object({
+    plugins: z.array(z.string()).default([]),
+    ent_ver: z.number().int().nonnegative().default(0),
+    // REQUIRED: a verified NEXUS agent-JWT always carries `exp` (short TTL). An
+    // exp-less token → `invalid_claims` at verify, so the gate's offline grace is
+    // always anchored on a signed freshness boundary (closes the exp-less edge).
+    exp: z.number().int().positive(),
+})
+    .passthrough();
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAYvB;8EAC8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC;KACD,WAAW,EAAE,CAAA"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nexus-mindgarden/plugin-license-foundation",
+  "version": "0.1.0",
+  "description": "Plugin-License Foundation — NEXUS entitlement LicenseGate (offline JWKS-verified, default-deny, last-known-good grace) + entitle-on-activation",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MrDewitt88/plugin-template.git",
+    "directory": "packages/plugin-license-foundation"
+  },
+  "homepage": "https://github.com/MrDewitt88/plugin-template/tree/main/packages/plugin-license-foundation#readme",
+  "bugs": {
+    "url": "https://github.com/MrDewitt88/plugin-template/issues"
+  },
+  "keywords": [
+    "nexus-mindgarden",
+    "plugin",
+    "license",
+    "entitlement",
+    "licensegate"
+  ],
+  "dependencies": {
+    "jose": "^5.9.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}