within-enforcement-sdk 1.0.0

package/dist/enforcement.d.ts

@@ -0,0 +1,25 @@
+import type { EnforcementConfig, Enforcement } from './types.js';
+/**
+ * Create an enforcement instance for gating MCP tool calls.
+ *
+ * Usage:
+ * ```typescript
+ * const within = createEnforcement({
+ *   vendorId: 'my-vendor',
+ *   apiUrl: 'https://within-actions.onrender.com',
+ *   apiKey: process.env.WITHIN_API_KEY,
+ *   toolScopeMap: {
+ *     search: 'data:read',
+ *     write_record: 'data:write',
+ *   },
+ * });
+ *
+ * // In your tool handler:
+ * const decision = await within.authorize('search', claims);
+ * if (!decision.allowed) return `Access denied: ${decision.reason}`;
+ * // ... run tool ...
+ * await within.complete('search', claims, 'success');
+ * ```
+ */
+export declare function createEnforcement(config: EnforcementConfig): Enforcement;
+//# sourceMappingURL=enforcement.d.ts.map

package/dist/enforcement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforcement.d.ts","sourceRoot":"","sources":["../src/enforcement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EAKjB,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAgGxE"}

package/dist/enforcement.js

@@ -0,0 +1,95 @@
+/**
+ * Create an enforcement instance for gating MCP tool calls.
+ *
+ * Usage:
+ * ```typescript
+ * const within = createEnforcement({
+ *   vendorId: 'my-vendor',
+ *   apiUrl: 'https://within-actions.onrender.com',
+ *   apiKey: process.env.WITHIN_API_KEY,
+ *   toolScopeMap: {
+ *     search: 'data:read',
+ *     write_record: 'data:write',
+ *   },
+ * });
+ *
+ * // In your tool handler:
+ * const decision = await within.authorize('search', claims);
+ * if (!decision.allowed) return `Access denied: ${decision.reason}`;
+ * // ... run tool ...
+ * await within.complete('search', claims, 'success');
+ * ```
+ */
+export function createEnforcement(config) {
+    const { vendorId, apiUrl, apiKey, toolScopeMap } = config;
+    async function authorize(toolName, claims) {
+        const userType = claims['https://within.com/user_type'];
+        // Customers pass straight through — Within is not involved
+        if (userType === 'customer') {
+            return { allowed: true, bypassed: true };
+        }
+        // Scope check (from token, no network call)
+        const requiredScope = toolScopeMap[toolName];
+        if (requiredScope) {
+            const userScopes = claims['https://within.com/scopes'] ?? [];
+            if (!userScopes.includes(requiredScope)) {
+                return { allowed: false, reason: 'scope_denied' };
+            }
+        }
+        // Quota check (live, hits the ledger)
+        const email = claims.email;
+        if (!email) {
+            return { allowed: false, reason: 'no_entitlement' };
+        }
+        try {
+            const res = await fetch(`${apiUrl}/api/ledger/${encodeURIComponent(email)}?vendor_id=${vendorId}`, { headers: { Authorization: `Bearer ${apiKey}` } });
+            if (!res.ok) {
+                return { allowed: false, reason: 'no_entitlement' };
+            }
+            const ledger = (await res.json());
+            if (!ledger.isActive) {
+                return { allowed: false, reason: 'inactive' };
+            }
+            if (ledger.quotaRemaining <= 0) {
+                return { allowed: false, reason: 'quota_exceeded' };
+            }
+            return { allowed: true };
+        }
+        catch {
+            // Network error — fail closed
+            return { allowed: false, reason: 'no_entitlement' };
+        }
+    }
+    async function complete(toolName, claims, outcome, opts) {
+        const userType = claims['https://within.com/user_type'];
+        // No-op for customers
+        if (userType === 'customer')
+            return;
+        const email = claims.email;
+        if (!email)
+            return;
+        try {
+            await fetch(`${apiUrl}/api/usage`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({
+                    vendor_id: vendorId,
+                    email,
+                    domain: claims['https://within.com/domain'],
+                    tool_name: toolName,
+                    outcome,
+                    agent_session_id: opts?.agentSessionId,
+                    latency_ms: opts?.latencyMs,
+                }),
+            });
+        }
+        catch {
+            // Fire-and-forget — don't break the tool call if metering fails
+        }
+    }
+    return { authorize, complete };
+}
+//# sourceMappingURL=enforcement.js.map

package/dist/enforcement.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createEnforcement } from './enforcement.js';
+export type { EnforcementConfig, WithinClaims, AuthorizeResult, DenialReason, Outcome, CompleteOptions, Enforcement, } 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":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,OAAO,EACP,eAAe,EACf,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createEnforcement } from './enforcement.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,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+/** Configuration for the enforcement SDK. */
+export interface EnforcementConfig {
+    /** Vendor identifier — must match the vendor_id used in Within's backend. */
+    vendorId: string;
+    /** Within API base URL (e.g. https://within-actions.onrender.com). */
+    apiUrl: string;
+    /** API key for authenticating with Within's ledger/usage endpoints. */
+    apiKey: string;
+    /**
+     * Maps each MCP tool name to the scope it requires.
+     * Tools not listed here are unrestricted.
+     *
+     * Available scopes (cumulative by tier):
+     *   Tier 0: tools:suggest
+     *   Tier 1: tools:run, data:read
+     *   Tier 2: data:write_limited
+     *   Tier 3: data:write, crm:read
+     *   Tier 4: crm:write_limited, analytics:read
+     */
+    toolScopeMap: Record<string, string>;
+}
+/** Within claims stamped into the Auth0 access token by the Auth0 Action. */
+export interface WithinClaims {
+    sub?: string;
+    email?: string;
+    'https://within.com/user_type'?: 'customer' | 'prospect' | 'personal';
+    'https://within.com/domain'?: string;
+    'https://within.com/tier'?: number;
+    'https://within.com/scopes'?: string[];
+    'https://within.com/icp_score'?: number;
+    [key: string]: unknown;
+}
+/** Result of an authorization check. */
+export interface AuthorizeResult {
+    /** Whether the tool call is allowed. */
+    allowed: boolean;
+    /** True when the user is a customer — enforcement was skipped entirely. */
+    bypassed?: boolean;
+    /** Reason for denial, if not allowed. */
+    reason?: DenialReason;
+}
+export type DenialReason = 'scope_denied' | 'quota_exceeded' | 'inactive' | 'no_entitlement';
+/** Options for the complete() call. */
+export interface CompleteOptions {
+    agentSessionId?: string;
+    latencyMs?: number;
+}
+export type Outcome = 'success' | 'failure' | 'quota_exceeded' | 'scope_denied';
+/** The enforcement instance returned by createEnforcement(). */
+export interface Enforcement {
+    /**
+     * Check if a tool call is allowed for the given user.
+     *
+     * - Customers: always allowed, no network calls.
+     * - Prospects: scope check (from token) + quota check (live, hits Within API).
+     */
+    authorize(toolName: string, claims: WithinClaims): Promise<AuthorizeResult>;
+    /**
+     * Report the outcome of a tool call.
+     *
+     * - Customers: no-op.
+     * - Prospects: records usage. Only 'success' increments quota.
+     *   Fire-and-forget — never throws.
+     */
+    complete(toolName: string, claims: WithinClaims, outcome: Outcome, opts?: CompleteOptions): Promise<void>;
+}
+//# 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":"AAAA,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IAEjB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IAEf,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;OAUG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8BAA8B,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;IACtE,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,2BAA2B,CAAC,EAAE,MAAM,EAAE,CAAC;IACvC,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,MAAM,YAAY,GACpB,cAAc,GACd,gBAAgB,GAChB,UAAU,GACV,gBAAgB,CAAC;AAErB,uCAAuC;AACvC,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAEhF,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAE5E;;;;;;OAMG;IACH,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,eAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "within-enforcement-sdk",
+  "version": "1.0.0",
+  "description": "Within GrowthAuth Enforcement SDK — scope checking, quota gating, and usage metering for MCP tool calls.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "within",
+    "mcp",
+    "enforcement",
+    "quota",
+    "scoping",
+    "trial",
+    "growthaauth"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}