@lelu-auth/lelu 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abenezer <abenezergetachew0923@gmail.com>
+
+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,55 @@
+# Lelu
+
+The TypeScript SDK for Lelu — the confidence-aware authorization engine for autonomous AI agents.
+
+Lelu provides confidence-aware access control, human-in-the-loop approvals, and SOC 2-ready audit trails for your autonomous agents.
+
+## Installation
+
+```bash
+npm install @lelu-auth/lelu
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from "@lelu-auth/lelu";
+
+// Initialize the client
+const lelu = createClient({ 
+  baseUrl: "http://localhost:8082" 
+});
+
+// Authorize an agent action
+async function runAgent() {
+  const { allowed, reason } = await lelu.agentAuthorize({
+    agentId: "agent-123",
+    action: "read_database",
+    resource: "users_table",
+    context: {
+      confidence: 0.95
+    }
+  });
+
+  if (allowed) {
+    console.log("Action permitted!");
+  } else {
+    console.log("Action denied:", reason);
+  }
+}
+```
+
+## Features
+
+- **Confidence-Aware**: Dynamically adjust permissions based on the AI agent's confidence level.
+- **Human-in-the-loop**: Require human approval for low-confidence or high-risk actions.
+- **Audit Trails**: SOC 2-ready logging of all agent decisions and actions.
+- **Framework Agnostic**: Works with LangChain, AutoGPT, or custom agent frameworks.
+
+## Documentation
+
+For full documentation, visit [https://github.com/lelu-auth/lelu](https://github.com/lelu-auth/lelu).
+
+## License
+
+MIT

package/dist/client-BD9h8CBT.d.mts

@@ -0,0 +1,235 @@
+import { z } from 'zod';
+
+declare const AuthRequestSchema: z.ZodObject<{
+    userId: z.ZodString;
+    action: z.ZodString;
+    resource: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    userId: string;
+    action: string;
+    resource?: Record<string, string> | undefined;
+}, {
+    userId: string;
+    action: string;
+    resource?: Record<string, string> | undefined;
+}>;
+declare const AgentContextSchema: z.ZodObject<{
+    /** LLM confidence score — 0.0 to 1.0 */
+    confidence: z.ZodNumber;
+    /** User the agent is acting on behalf of */
+    actingFor: z.ZodOptional<z.ZodString>;
+    /** Requested agent scope */
+    scope: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    confidence: number;
+    actingFor?: string | undefined;
+    scope?: string | undefined;
+}, {
+    confidence: number;
+    actingFor?: string | undefined;
+    scope?: string | undefined;
+}>;
+declare const AgentAuthRequestSchema: z.ZodObject<{
+    actor: z.ZodString;
+    action: z.ZodString;
+    resource: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    context: z.ZodObject<{
+        /** LLM confidence score — 0.0 to 1.0 */
+        confidence: z.ZodNumber;
+        /** User the agent is acting on behalf of */
+        actingFor: z.ZodOptional<z.ZodString>;
+        /** Requested agent scope */
+        scope: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        confidence: number;
+        actingFor?: string | undefined;
+        scope?: string | undefined;
+    }, {
+        confidence: number;
+        actingFor?: string | undefined;
+        scope?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    action: string;
+    actor: string;
+    context: {
+        confidence: number;
+        actingFor?: string | undefined;
+        scope?: string | undefined;
+    };
+    resource?: Record<string, string> | undefined;
+}, {
+    action: string;
+    actor: string;
+    context: {
+        confidence: number;
+        actingFor?: string | undefined;
+        scope?: string | undefined;
+    };
+    resource?: Record<string, string> | undefined;
+}>;
+declare const MintTokenRequestSchema: z.ZodObject<{
+    scope: z.ZodString;
+    actingFor: z.ZodOptional<z.ZodString>;
+    ttlSeconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    scope: string;
+    actingFor?: string | undefined;
+    ttlSeconds?: number | undefined;
+}, {
+    scope: string;
+    actingFor?: string | undefined;
+    ttlSeconds?: number | undefined;
+}>;
+declare const DelegateScopeRequestSchema: z.ZodObject<{
+    delegator: z.ZodString;
+    delegatee: z.ZodString;
+    scopedTo: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ttlSeconds: z.ZodOptional<z.ZodNumber>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    actingFor: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    delegator: string;
+    delegatee: string;
+    confidence?: number | undefined;
+    actingFor?: string | undefined;
+    ttlSeconds?: number | undefined;
+    scopedTo?: string[] | undefined;
+    tenantId?: string | undefined;
+}, {
+    delegator: string;
+    delegatee: string;
+    confidence?: number | undefined;
+    actingFor?: string | undefined;
+    ttlSeconds?: number | undefined;
+    scopedTo?: string[] | undefined;
+    tenantId?: string | undefined;
+}>;
+interface AuthDecision {
+    allowed: boolean;
+    reason: string;
+    traceId: string;
+}
+interface AgentAuthDecision {
+    allowed: boolean;
+    reason: string;
+    traceId: string;
+    downgradedScope: string | undefined;
+    requiresHumanReview: boolean;
+    confidenceUsed: number;
+}
+interface MintTokenResult {
+    token: string;
+    tokenId: string;
+    expiresAt: Date;
+}
+interface DelegateScopeRequest {
+    /** Agent delegating the scope */
+    delegator: string;
+    /** Agent receiving the constrained sub-scope */
+    delegatee: string;
+    /** Actions to grant (must be subset of policy's can_delegate.scoped_to) */
+    scopedTo?: string[];
+    /** Token TTL in seconds — capped by the policy's max_ttl_seconds */
+    ttlSeconds?: number;
+    /** Delegator's confidence score — checked against require_confidence_above */
+    confidence?: number;
+    /** User the delegated agent acts on behalf of */
+    actingFor?: string;
+    tenantId?: string;
+}
+interface DelegateScopeResult {
+    token: string;
+    tokenId: string;
+    expiresAt: Date;
+    delegator: string;
+    delegatee: string;
+    grantedScopes: string[];
+    traceId: string;
+}
+interface RevokeTokenResult {
+    success: boolean;
+}
+type AuthRequest = z.infer<typeof AuthRequestSchema>;
+type AgentAuthRequest = z.infer<typeof AgentAuthRequestSchema>;
+type AgentContext = z.infer<typeof AgentContextSchema>;
+type MintTokenRequest = z.infer<typeof MintTokenRequestSchema>;
+interface ClientConfig {
+    /** Base URL of the Auth Permission Engine (default: http://localhost:8080) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+    /** Optional bearer token for authenticating with the engine */
+    apiKey?: string;
+}
+declare class AuthEngineError extends Error {
+    readonly status?: number | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, details?: unknown | undefined);
+}
+
+/**
+ * LeluClient is the core SDK entry-point. It communicates with the local
+ * Auth Permission Engine sidecar over HTTP/JSON.
+ *
+ * @example
+ * ```ts
+ * const lelu = new LeluClient({ baseUrl: "http://localhost:8080" });
+ *
+ * const decision = await lelu.agentAuthorize({
+ *   actor: "invoice_bot",
+ *   action: "approve_refunds",
+ *   context: { confidence: 0.92, actingFor: "user_123" },
+ * });
+ *
+ * if (!decision.allowed) {
+ *   console.log(decision.reason);
+ * }
+ * ```
+ */
+declare class LeluClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly apiKey;
+    constructor(cfg?: ClientConfig);
+    /**
+     * Checks whether a human user is permitted to perform an action.
+     */
+    authorize(req: AuthRequest): Promise<AuthDecision>;
+    /**
+     * Checks whether an AI agent is permitted to perform an action, taking the
+     * confidence score into account (Confidence-Aware Auth ★).
+     */
+    agentAuthorize(req: AgentAuthRequest): Promise<AgentAuthDecision>;
+    /**
+     * Mints a scoped JWT for an agent with an optional TTL.
+     * Default TTL is 60 seconds.
+     */
+    mintToken(req: MintTokenRequest): Promise<MintTokenResult>;
+    /**
+     * Immediately revokes a JIT token by its ID.
+     */
+    revokeToken(tokenId: string): Promise<RevokeTokenResult>;
+    /**
+     * Delegates a constrained sub-scope from one agent to another.
+     *
+     * Validates the delegation rule in the loaded policy, caps the TTL to the
+     * policy maximum, and mints a child JIT token scoped to the granted actions.
+     *
+     * The delegator's `confidence` score is checked against the policy's
+     * `require_confidence_above` before delegation is granted.
+     */
+    delegateScope(req: DelegateScopeRequest): Promise<DelegateScopeResult>;
+    /**
+     * Returns true if the engine is reachable and healthy.
+     */
+    isHealthy(): Promise<boolean>;
+    private headers;
+    private post;
+    private delete;
+    private get;
+    private parseResponse;
+}
+
+export { type AgentAuthDecision as A, type ClientConfig as C, type DelegateScopeRequest as D, LeluClient as L, type MintTokenRequest as M, type RevokeTokenResult as R, type AgentAuthRequest as a, AgentAuthRequestSchema as b, type AgentContext as c, AgentContextSchema as d, type AuthDecision as e, AuthEngineError as f, type AuthRequest as g, AuthRequestSchema as h, DelegateScopeRequestSchema as i, type DelegateScopeResult as j, MintTokenRequestSchema as k, type MintTokenResult as l };

package/dist/client-BD9h8CBT.d.ts

@@ -0,0 +1,235 @@
+import { z } from 'zod';
+
+declare const AuthRequestSchema: z.ZodObject<{
+    userId: z.ZodString;
+    action: z.ZodString;
+    resource: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    userId: string;
+    action: string;
+    resource?: Record<string, string> | undefined;
+}, {
+    userId: string;
+    action: string;
+    resource?: Record<string, string> | undefined;
+}>;
+declare const AgentContextSchema: z.ZodObject<{
+    /** LLM confidence score — 0.0 to 1.0 */
+    confidence: z.ZodNumber;
+    /** User the agent is acting on behalf of */
+    actingFor: z.ZodOptional<z.ZodString>;
+    /** Requested agent scope */
+    scope: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    confidence: number;
+    actingFor?: string | undefined;
+    scope?: string | undefined;
+}, {
+    confidence: number;
+    actingFor?: string | undefined;
+    scope?: string | undefined;
+}>;
+declare const AgentAuthRequestSchema: z.ZodObject<{
+    actor: z.ZodString;
+    action: z.ZodString;
+    resource: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    context: z.ZodObject<{
+        /** LLM confidence score — 0.0 to 1.0 */
+        confidence: z.ZodNumber;
+        /** User the agent is acting on behalf of */
+        actingFor: z.ZodOptional<z.ZodString>;
+        /** Requested agent scope */
+        scope: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        confidence: number;
+        actingFor?: string | undefined;
+        scope?: string | undefined;
+    }, {
+        confidence: number;
+        actingFor?: string | undefined;
+        scope?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    action: string;
+    actor: string;
+    context: {
+        confidence: number;
+        actingFor?: string | undefined;
+        scope?: string | undefined;
+    };
+    resource?: Record<string, string> | undefined;
+}, {
+    action: string;
+    actor: string;
+    context: {
+        confidence: number;
+        actingFor?: string | undefined;
+        scope?: string | undefined;
+    };
+    resource?: Record<string, string> | undefined;
+}>;
+declare const MintTokenRequestSchema: z.ZodObject<{
+    scope: z.ZodString;
+    actingFor: z.ZodOptional<z.ZodString>;
+    ttlSeconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    scope: string;
+    actingFor?: string | undefined;
+    ttlSeconds?: number | undefined;
+}, {
+    scope: string;
+    actingFor?: string | undefined;
+    ttlSeconds?: number | undefined;
+}>;
+declare const DelegateScopeRequestSchema: z.ZodObject<{
+    delegator: z.ZodString;
+    delegatee: z.ZodString;
+    scopedTo: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ttlSeconds: z.ZodOptional<z.ZodNumber>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    actingFor: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    delegator: string;
+    delegatee: string;
+    confidence?: number | undefined;
+    actingFor?: string | undefined;
+    ttlSeconds?: number | undefined;
+    scopedTo?: string[] | undefined;
+    tenantId?: string | undefined;
+}, {
+    delegator: string;
+    delegatee: string;
+    confidence?: number | undefined;
+    actingFor?: string | undefined;
+    ttlSeconds?: number | undefined;
+    scopedTo?: string[] | undefined;
+    tenantId?: string | undefined;
+}>;
+interface AuthDecision {
+    allowed: boolean;
+    reason: string;
+    traceId: string;
+}
+interface AgentAuthDecision {
+    allowed: boolean;
+    reason: string;
+    traceId: string;
+    downgradedScope: string | undefined;
+    requiresHumanReview: boolean;
+    confidenceUsed: number;
+}
+interface MintTokenResult {
+    token: string;
+    tokenId: string;
+    expiresAt: Date;
+}
+interface DelegateScopeRequest {
+    /** Agent delegating the scope */
+    delegator: string;
+    /** Agent receiving the constrained sub-scope */
+    delegatee: string;
+    /** Actions to grant (must be subset of policy's can_delegate.scoped_to) */
+    scopedTo?: string[];
+    /** Token TTL in seconds — capped by the policy's max_ttl_seconds */
+    ttlSeconds?: number;
+    /** Delegator's confidence score — checked against require_confidence_above */
+    confidence?: number;
+    /** User the delegated agent acts on behalf of */
+    actingFor?: string;
+    tenantId?: string;
+}
+interface DelegateScopeResult {
+    token: string;
+    tokenId: string;
+    expiresAt: Date;
+    delegator: string;
+    delegatee: string;
+    grantedScopes: string[];
+    traceId: string;
+}
+interface RevokeTokenResult {
+    success: boolean;
+}
+type AuthRequest = z.infer<typeof AuthRequestSchema>;
+type AgentAuthRequest = z.infer<typeof AgentAuthRequestSchema>;
+type AgentContext = z.infer<typeof AgentContextSchema>;
+type MintTokenRequest = z.infer<typeof MintTokenRequestSchema>;
+interface ClientConfig {
+    /** Base URL of the Auth Permission Engine (default: http://localhost:8080) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+    /** Optional bearer token for authenticating with the engine */
+    apiKey?: string;
+}
+declare class AuthEngineError extends Error {
+    readonly status?: number | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, details?: unknown | undefined);
+}
+
+/**
+ * LeluClient is the core SDK entry-point. It communicates with the local
+ * Auth Permission Engine sidecar over HTTP/JSON.
+ *
+ * @example
+ * ```ts
+ * const lelu = new LeluClient({ baseUrl: "http://localhost:8080" });
+ *
+ * const decision = await lelu.agentAuthorize({
+ *   actor: "invoice_bot",
+ *   action: "approve_refunds",
+ *   context: { confidence: 0.92, actingFor: "user_123" },
+ * });
+ *
+ * if (!decision.allowed) {
+ *   console.log(decision.reason);
+ * }
+ * ```
+ */
+declare class LeluClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly apiKey;
+    constructor(cfg?: ClientConfig);
+    /**
+     * Checks whether a human user is permitted to perform an action.
+     */
+    authorize(req: AuthRequest): Promise<AuthDecision>;
+    /**
+     * Checks whether an AI agent is permitted to perform an action, taking the
+     * confidence score into account (Confidence-Aware Auth ★).
+     */
+    agentAuthorize(req: AgentAuthRequest): Promise<AgentAuthDecision>;
+    /**
+     * Mints a scoped JWT for an agent with an optional TTL.
+     * Default TTL is 60 seconds.
+     */
+    mintToken(req: MintTokenRequest): Promise<MintTokenResult>;
+    /**
+     * Immediately revokes a JIT token by its ID.
+     */
+    revokeToken(tokenId: string): Promise<RevokeTokenResult>;
+    /**
+     * Delegates a constrained sub-scope from one agent to another.
+     *
+     * Validates the delegation rule in the loaded policy, caps the TTL to the
+     * policy maximum, and mints a child JIT token scoped to the granted actions.
+     *
+     * The delegator's `confidence` score is checked against the policy's
+     * `require_confidence_above` before delegation is granted.
+     */
+    delegateScope(req: DelegateScopeRequest): Promise<DelegateScopeResult>;
+    /**
+     * Returns true if the engine is reachable and healthy.
+     */
+    isHealthy(): Promise<boolean>;
+    private headers;
+    private post;
+    private delete;
+    private get;
+    private parseResponse;
+}
+
+export { type AgentAuthDecision as A, type ClientConfig as C, type DelegateScopeRequest as D, LeluClient as L, type MintTokenRequest as M, type RevokeTokenResult as R, type AgentAuthRequest as a, AgentAuthRequestSchema as b, type AgentContext as c, AgentContextSchema as d, type AuthDecision as e, AuthEngineError as f, type AuthRequest as g, AuthRequestSchema as h, DelegateScopeRequestSchema as i, type DelegateScopeResult as j, MintTokenRequestSchema as k, type MintTokenResult as l };

package/dist/express/index.d.mts

@@ -0,0 +1,31 @@
+import { RequestHandler } from 'express';
+import { L as LeluClient } from '../client-BD9h8CBT.mjs';
+import 'zod';
+
+interface AuthorizeOptions {
+    /** Base URL of the Lelu engine (default: http://localhost:8080) */
+    baseUrl?: string;
+    /** API key for the Lelu engine */
+    apiKey?: string;
+    /** HTTP header that carries the actor identifier (default: x-actor) */
+    actorHeader?: string;
+    /** Confidence score to pass to the engine (default: 1.0) */
+    confidence?: number;
+    /** Explicit LeluClient instance (overrides baseUrl/apiKey) */
+    client?: LeluClient;
+}
+/**
+ * Express middleware factory that calls the Lelu engine and either calls
+ * `next()` (allowed) or returns a 403 JSON response (denied / human_review).
+ *
+ * ```ts
+ * import express from "express";
+ * import { authorize } from "@lelu/sdk/express";
+ *
+ * const app = express();
+ * app.get("/sensitive", authorize("files.read", { confidence: 0.9 }), handler);
+ * ```
+ */
+declare function authorize(action: string, opts?: AuthorizeOptions): RequestHandler;
+
+export { type AuthorizeOptions, authorize };

package/dist/express/index.d.ts

@@ -0,0 +1,31 @@
+import { RequestHandler } from 'express';
+import { L as LeluClient } from '../client-BD9h8CBT.js';
+import 'zod';
+
+interface AuthorizeOptions {
+    /** Base URL of the Lelu engine (default: http://localhost:8080) */
+    baseUrl?: string;
+    /** API key for the Lelu engine */
+    apiKey?: string;
+    /** HTTP header that carries the actor identifier (default: x-actor) */
+    actorHeader?: string;
+    /** Confidence score to pass to the engine (default: 1.0) */
+    confidence?: number;
+    /** Explicit LeluClient instance (overrides baseUrl/apiKey) */
+    client?: LeluClient;
+}
+/**
+ * Express middleware factory that calls the Lelu engine and either calls
+ * `next()` (allowed) or returns a 403 JSON response (denied / human_review).
+ *
+ * ```ts
+ * import express from "express";
+ * import { authorize } from "@lelu/sdk/express";
+ *
+ * const app = express();
+ * app.get("/sensitive", authorize("files.read", { confidence: 0.9 }), handler);
+ * ```
+ */
+declare function authorize(action: string, opts?: AuthorizeOptions): RequestHandler;
+
+export { type AuthorizeOptions, authorize };