@nobulex/sdk 0.1.0

package/dist/adapters/express.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Express/HTTP middleware adapter for the Stele SDK.
+ *
+ * Provides zero-config HTTP middleware that wraps any Express/Connect-compatible
+ * handler with Stele covenant enforcement. Uses generic request/response types
+ * so it works with Express, Koa, Hono, Fastify, and any Connect-compatible server.
+ *
+ * @packageDocumentation
+ */
+import type { SteleClient } from '../index.js';
+import type { CovenantDocument } from '@nobulex/core';
+import type { EvaluationResult } from '../types.js';
+/**
+ * Generic incoming request interface.
+ *
+ * Compatible with Express, Koa, Hono, Fastify, and Node.js http.IncomingMessage.
+ */
+export interface IncomingRequest {
+    /** HTTP method (GET, POST, PUT, DELETE, etc.). */
+    method?: string;
+    /** Full URL string. */
+    url?: string;
+    /** Parsed path component of the URL (Express-style). */
+    path?: string;
+    /** Request headers. */
+    headers?: Record<string, string | string[] | undefined>;
+}
+/**
+ * Generic outgoing response interface.
+ *
+ * Compatible with Express, Koa, Hono, Fastify, and Node.js http.ServerResponse.
+ */
+export interface OutgoingResponse {
+    /** HTTP status code. */
+    statusCode?: number;
+    /** Set a response header. */
+    setHeader?: (name: string, value: string) => void;
+    /** End the response with an optional body. */
+    end?: (body?: string) => void;
+}
+/**
+ * Connect/Express-style next function.
+ */
+export type NextFunction = (err?: unknown) => void;
+/**
+ * Options for the steleMiddleware factory.
+ */
+export interface SteleMiddlewareOptions {
+    /** The SteleClient instance to use for covenant evaluation. */
+    client: SteleClient;
+    /** The covenant document to enforce. */
+    covenant: CovenantDocument;
+    /**
+     * Extract the action string from the incoming request.
+     * Defaults to `req.method?.toLowerCase() ?? 'read'`.
+     */
+    actionExtractor?: (req: IncomingRequest) => string;
+    /**
+     * Extract the resource string from the incoming request.
+     * Defaults to `req.path ?? req.url ?? '/'`.
+     */
+    resourceExtractor?: (req: IncomingRequest) => string;
+    /**
+     * Custom handler for denied requests. If not provided, responds
+     * with a 403 JSON body.
+     */
+    onDenied?: (req: IncomingRequest, res: OutgoingResponse, result: EvaluationResult) => void;
+    /**
+     * Custom handler for errors during evaluation. If not provided,
+     * responds with a 500 JSON body.
+     */
+    onError?: (req: IncomingRequest, res: OutgoingResponse, error: unknown) => void;
+}
+/**
+ * Options for the steleGuardHandler factory.
+ */
+export interface SteleGuardHandlerOptions {
+    /** The SteleClient instance to use for covenant evaluation. */
+    client: SteleClient;
+    /** The covenant document to enforce. */
+    covenant: CovenantDocument;
+    /**
+     * Extract the action string from the incoming request.
+     * Defaults to `req.method?.toLowerCase() ?? 'read'`.
+     */
+    actionExtractor?: (req: IncomingRequest) => string;
+    /**
+     * Extract the resource string from the incoming request.
+     * Defaults to `req.path ?? req.url ?? '/'`.
+     */
+    resourceExtractor?: (req: IncomingRequest) => string;
+    /**
+     * Custom handler for denied requests. If not provided, responds
+     * with a 403 JSON body.
+     */
+    onDenied?: (req: IncomingRequest, res: OutgoingResponse, result: EvaluationResult) => void;
+    /**
+     * Custom handler for errors during evaluation. If not provided,
+     * responds with a 500 JSON body.
+     */
+    onError?: (req: IncomingRequest, res: OutgoingResponse, error: unknown) => void;
+}
+/**
+ * Options for the createCovenantRouter factory.
+ */
+export interface CovenantRouterOptions {
+    /** The SteleClient instance to use for covenant evaluation. */
+    client: SteleClient;
+    /** The covenant document to enforce. */
+    covenant: CovenantDocument;
+}
+/**
+ * Connect-compatible middleware factory that enforces a Stele covenant
+ * on every incoming HTTP request.
+ *
+ * For each request:
+ * - Extracts the action and resource using configurable extractors
+ * - Evaluates them against the covenant's CCL constraints
+ * - If permitted: sets `x-stele-permitted: true` header and calls `next()`
+ * - If denied: calls `onDenied` handler (default: 403 JSON response)
+ * - On error: calls `onError` handler (default: 500 JSON response)
+ *
+ * @param options - Middleware configuration options.
+ * @returns A Connect-compatible middleware function `(req, res, next) => void`.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { SteleClient, steleMiddleware } from '@nobulex/sdk';
+ *
+ * const client = new SteleClient();
+ * const app = express();
+ *
+ * app.use(steleMiddleware({
+ *   client,
+ *   covenant: myCovenantDoc,
+ * }));
+ *
+ * app.get('/data', (req, res) => {
+ *   res.json({ data: 'allowed!' });
+ * });
+ * ```
+ */
+export declare function steleMiddleware(options: SteleMiddlewareOptions): (req: IncomingRequest, res: OutgoingResponse, next: NextFunction) => void;
+/**
+ * Async handler type compatible with any HTTP framework.
+ */
+export type AsyncHandler = (req: IncomingRequest, res: OutgoingResponse) => Promise<void>;
+/**
+ * Wraps an async handler with Stele covenant enforcement for standalone use
+ * (no next function required).
+ *
+ * Evaluates the request against the covenant before invoking the handler.
+ * If denied, the handler is never called and a 403 response is sent.
+ *
+ * @param options - Guard handler configuration options.
+ * @param handler - The async handler to wrap.
+ * @returns A new handler function that enforces the covenant before delegation.
+ *
+ * @example
+ * ```typescript
+ * const guardedHandler = steleGuardHandler(
+ *   { client, covenant: myDoc },
+ *   async (req, res) => {
+ *     res.end(JSON.stringify({ data: 'success' }));
+ *   },
+ * );
+ *
+ * // Use with any framework
+ * http.createServer(guardedHandler);
+ * ```
+ */
+export declare function steleGuardHandler(options: SteleGuardHandlerOptions, handler: AsyncHandler): (req: IncomingRequest, res: OutgoingResponse) => Promise<void>;
+/**
+ * Options for the well-known Stele discovery endpoint.
+ * See docs/DISCOVERY.md for the convention.
+ */
+export interface WellKnownOptions {
+    /** Agent identity or content-address. */
+    agentId: string;
+    /** Covenant entries for discovery. */
+    covenants: Array<{
+        id: string;
+        url: string;
+        status: 'active' | 'expired' | 'revoked';
+    }>;
+    /** Optional base URL for resolver (e.g. https://example.com/stele/resolve). */
+    resolver?: string;
+    /** Protocol version. Defaults to "0.1.0". */
+    stele?: string;
+}
+/**
+ * Creates a handler for GET /.well-known/stele (federated covenant discovery).
+ * Trust the Ed25519 signature on the covenant, not the resolver.
+ *
+ * @param options - Discovery metadata.
+ * @returns AsyncHandler for the well-known endpoint.
+ *
+ * @example
+ * ```typescript
+ * const handler = createWellKnownHandler({
+ *   agentId: 'agent-1',
+ *   covenants: [{ id: doc.id, url: 'https://example.com/covenants/abc.json', status: 'active' }],
+ * });
+ * app.get('/.well-known/stele', handler);
+ * ```
+ */
+export declare function createWellKnownHandler(options: WellKnownOptions): AsyncHandler;
+/**
+ * A covenant router that provides fine-grained enforcement helpers.
+ */
+export interface CovenantRouter {
+    /**
+     * Returns middleware that enforces a specific action/resource pair.
+     *
+     * Unlike `steleMiddleware` which extracts action/resource from the request,
+     * this allows you to specify exact values for route-level enforcement.
+     *
+     * @param action - The action to enforce (e.g., `"read"`, `"write"`).
+     * @param resource - The resource to enforce (e.g., `"/data/users"`).
+     * @returns A Connect-compatible middleware function.
+     *
+     * @example
+     * ```typescript
+     * const router = createCovenantRouter({ client, covenant });
+     *
+     * app.get('/users', router.protect('read', '/users'), getUsers);
+     * app.post('/users', router.protect('write', '/users'), createUser);
+     * ```
+     */
+    protect: (action: string, resource: string) => (req: IncomingRequest, res: OutgoingResponse, next: NextFunction) => void;
+    /**
+     * Evaluates a request against the covenant and returns the result
+     * without sending a response.
+     *
+     * Useful for custom enforcement logic or logging.
+     *
+     * @param req - The incoming request to evaluate.
+     * @returns A promise resolving to the EvaluationResult.
+     *
+     * @example
+     * ```typescript
+     * const router = createCovenantRouter({ client, covenant });
+     * const result = await router.evaluateRequest(req);
+     * if (result.permitted) {
+     *   // custom handling
+     * }
+     * ```
+     */
+    evaluateRequest: (req: IncomingRequest) => Promise<EvaluationResult>;
+}
+/**
+ * Creates a covenant router with fine-grained enforcement helpers.
+ *
+ * Provides `.protect(action, resource)` for route-level enforcement and
+ * `.evaluateRequest(req)` for programmatic access to evaluation results.
+ *
+ * @param options - Router configuration options.
+ * @returns A CovenantRouter instance.
+ *
+ * @example
+ * ```typescript
+ * const router = createCovenantRouter({ client, covenant: myDoc });
+ *
+ * // Route-level protection
+ * app.get('/data', router.protect('read', '/data'), handler);
+ *
+ * // Programmatic evaluation
+ * const result = await router.evaluateRequest(req);
+ * ```
+ */
+export declare function createCovenantRouter(options: CovenantRouterOptions): CovenantRouter;
+/**
+ * Options for the Kova API Gateway middleware.
+ *
+ * Drop-in middleware that sits in front of any API and requires agents
+ * to present a valid covenant before granting access. Protects API providers
+ * from liability when agents misuse their API.
+ *
+ * @see docs/ADOPTION-STRATEGY.md — "Trust-Gated Access: The Liability Play"
+ */
+export interface KovaGatewayOptions {
+    /** The SteleClient instance for covenant verification and evaluation. */
+    client: SteleClient;
+    /**
+     * Extract the covenant from the incoming request.
+     * Default: reads `x-kova-covenant` header as JSON string, or `authorization: Bearer <base64>`.
+     */
+    covenantExtractor?: (req: IncomingRequest) => CovenantDocument | string | null;
+    /**
+     * Optional: required constraints the client's covenant must satisfy.
+     * If provided, the gateway checks that the covenant's CCL includes these.
+     */
+    requiredConstraints?: string[];
+    actionExtractor?: (req: IncomingRequest) => string;
+    resourceExtractor?: (req: IncomingRequest) => string;
+    onDenied?: (req: IncomingRequest, res: OutgoingResponse, result: EvaluationResult) => void;
+    onError?: (req: IncomingRequest, res: OutgoingResponse, error: unknown) => void;
+}
+/**
+ * Kova API Gateway middleware — requires agents to present a valid covenant before API access.
+ *
+ * Drop-in middleware for Express/Connect. Every agent calling the API must present
+ * a covenant (via `x-kova-covenant` header or `Authorization: Bearer <base64>`).
+ * The gateway verifies the covenant and evaluates the request. Protects API
+ * providers from liability when agents misuse their API.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { SteleClient, kovaGatewayMiddleware } from '@nobulex/sdk';
+ *
+ * const client = new SteleClient();
+ * const app = express();
+ *
+ * app.use(kovaGatewayMiddleware({ client }));
+ *
+ * app.get('/data', (req, res) => res.json({ data: 'allowed' }));
+ * ```
+ */
+export declare function kovaGatewayMiddleware(options: KovaGatewayOptions): (req: IncomingRequest, res: OutgoingResponse, next: NextFunction) => void;
+//# sourceMappingURL=express.d.ts.map

package/dist/adapters/express.d.ts.map

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

package/dist/adapters/express.js

@@ -0,0 +1,356 @@
+/**
+ * Express/HTTP middleware adapter for the Stele SDK.
+ *
+ * Provides zero-config HTTP middleware that wraps any Express/Connect-compatible
+ * handler with Stele covenant enforcement. Uses generic request/response types
+ * so it works with Express, Koa, Hono, Fastify, and any Connect-compatible server.
+ *
+ * @packageDocumentation
+ */
+import { deserializeCovenant, verifyCovenant } from '@nobulex/core';
+// ─── Default extractors ──────────────────────────────────────────────────────
+/**
+ * Default action extractor: maps HTTP method to a lowercase action string.
+ */
+function defaultActionExtractor(req) {
+    return req.method?.toLowerCase() ?? 'read';
+}
+/**
+ * Default resource extractor: uses the request path or URL.
+ */
+function defaultResourceExtractor(req) {
+    return req.path ?? req.url ?? '/';
+}
+/**
+ * Default denied handler: sends a 403 JSON response.
+ */
+function defaultOnDenied(_req, res, result) {
+    if (res.statusCode !== undefined) {
+        res.statusCode = 403;
+    }
+    if (res.setHeader) {
+        res.setHeader('content-type', 'application/json');
+        res.setHeader('x-stele-permitted', 'false');
+    }
+    if (res.end) {
+        res.end(JSON.stringify({
+            error: 'Forbidden',
+            permitted: false,
+            reason: result.reason ?? 'Request denied by covenant',
+        }));
+    }
+}
+/**
+ * Default error handler: sends a 500 JSON response.
+ */
+function defaultOnError(_req, res, error) {
+    if (res.statusCode !== undefined) {
+        res.statusCode = 500;
+    }
+    if (res.setHeader) {
+        res.setHeader('content-type', 'application/json');
+    }
+    if (res.end) {
+        res.end(JSON.stringify({
+            error: 'Internal Server Error',
+            message: error instanceof Error ? error.message : 'Covenant evaluation failed',
+        }));
+    }
+}
+// ─── steleMiddleware ─────────────────────────────────────────────────────────
+/**
+ * Connect-compatible middleware factory that enforces a Stele covenant
+ * on every incoming HTTP request.
+ *
+ * For each request:
+ * - Extracts the action and resource using configurable extractors
+ * - Evaluates them against the covenant's CCL constraints
+ * - If permitted: sets `x-stele-permitted: true` header and calls `next()`
+ * - If denied: calls `onDenied` handler (default: 403 JSON response)
+ * - On error: calls `onError` handler (default: 500 JSON response)
+ *
+ * @param options - Middleware configuration options.
+ * @returns A Connect-compatible middleware function `(req, res, next) => void`.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { SteleClient, steleMiddleware } from '@nobulex/sdk';
+ *
+ * const client = new SteleClient();
+ * const app = express();
+ *
+ * app.use(steleMiddleware({
+ *   client,
+ *   covenant: myCovenantDoc,
+ * }));
+ *
+ * app.get('/data', (req, res) => {
+ *   res.json({ data: 'allowed!' });
+ * });
+ * ```
+ */
+export function steleMiddleware(options) {
+    const { client, covenant, actionExtractor = defaultActionExtractor, resourceExtractor = defaultResourceExtractor, onDenied = defaultOnDenied, onError = defaultOnError, } = options;
+    return (req, res, next) => {
+        const action = actionExtractor(req);
+        const resource = resourceExtractor(req);
+        client
+            .evaluateAction(covenant, action, resource)
+            .then((result) => {
+            if (result.permitted) {
+                if (res.setHeader) {
+                    res.setHeader('x-stele-permitted', 'true');
+                }
+                next();
+            }
+            else {
+                onDenied(req, res, result);
+            }
+        })
+            .catch((error) => {
+            onError(req, res, error);
+        });
+    };
+}
+/**
+ * Wraps an async handler with Stele covenant enforcement for standalone use
+ * (no next function required).
+ *
+ * Evaluates the request against the covenant before invoking the handler.
+ * If denied, the handler is never called and a 403 response is sent.
+ *
+ * @param options - Guard handler configuration options.
+ * @param handler - The async handler to wrap.
+ * @returns A new handler function that enforces the covenant before delegation.
+ *
+ * @example
+ * ```typescript
+ * const guardedHandler = steleGuardHandler(
+ *   { client, covenant: myDoc },
+ *   async (req, res) => {
+ *     res.end(JSON.stringify({ data: 'success' }));
+ *   },
+ * );
+ *
+ * // Use with any framework
+ * http.createServer(guardedHandler);
+ * ```
+ */
+export function steleGuardHandler(options, handler) {
+    const { client, covenant, actionExtractor = defaultActionExtractor, resourceExtractor = defaultResourceExtractor, onDenied = defaultOnDenied, onError = defaultOnError, } = options;
+    return async (req, res) => {
+        const action = actionExtractor(req);
+        const resource = resourceExtractor(req);
+        try {
+            const result = await client.evaluateAction(covenant, action, resource);
+            if (result.permitted) {
+                if (res.setHeader) {
+                    res.setHeader('x-stele-permitted', 'true');
+                }
+                await handler(req, res);
+            }
+            else {
+                onDenied(req, res, result);
+            }
+        }
+        catch (error) {
+            onError(req, res, error);
+        }
+    };
+}
+/**
+ * Creates a handler for GET /.well-known/stele (federated covenant discovery).
+ * Trust the Ed25519 signature on the covenant, not the resolver.
+ *
+ * @param options - Discovery metadata.
+ * @returns AsyncHandler for the well-known endpoint.
+ *
+ * @example
+ * ```typescript
+ * const handler = createWellKnownHandler({
+ *   agentId: 'agent-1',
+ *   covenants: [{ id: doc.id, url: 'https://example.com/covenants/abc.json', status: 'active' }],
+ * });
+ * app.get('/.well-known/stele', handler);
+ * ```
+ */
+export function createWellKnownHandler(options) {
+    const { agentId, covenants, resolver, stele = '0.1.0' } = options;
+    return async (_req, res) => {
+        const body = JSON.stringify({
+            stele,
+            agentId,
+            covenants,
+            ...(resolver && { resolver }),
+        });
+        if (res.setHeader) {
+            res.setHeader('content-type', 'application/json');
+            res.setHeader('cache-control', 'public, max-age=60');
+        }
+        if (res.statusCode !== undefined) {
+            res.statusCode = 200;
+        }
+        if (res.end) {
+            res.end(body);
+        }
+    };
+}
+/**
+ * Creates a covenant router with fine-grained enforcement helpers.
+ *
+ * Provides `.protect(action, resource)` for route-level enforcement and
+ * `.evaluateRequest(req)` for programmatic access to evaluation results.
+ *
+ * @param options - Router configuration options.
+ * @returns A CovenantRouter instance.
+ *
+ * @example
+ * ```typescript
+ * const router = createCovenantRouter({ client, covenant: myDoc });
+ *
+ * // Route-level protection
+ * app.get('/data', router.protect('read', '/data'), handler);
+ *
+ * // Programmatic evaluation
+ * const result = await router.evaluateRequest(req);
+ * ```
+ */
+export function createCovenantRouter(options) {
+    const { client, covenant } = options;
+    return {
+        protect(action, resource) {
+            return (_req, res, next) => {
+                client
+                    .evaluateAction(covenant, action, resource)
+                    .then((result) => {
+                    if (result.permitted) {
+                        if (res.setHeader) {
+                            res.setHeader('x-stele-permitted', 'true');
+                        }
+                        next();
+                    }
+                    else {
+                        defaultOnDenied(_req, res, result);
+                    }
+                })
+                    .catch((error) => {
+                    defaultOnError(_req, res, error);
+                });
+            };
+        },
+        async evaluateRequest(req) {
+            const action = defaultActionExtractor(req);
+            const resource = defaultResourceExtractor(req);
+            return client.evaluateAction(covenant, action, resource);
+        },
+    };
+}
+function defaultCovenantExtractor(req) {
+    const h = req.headers ?? {};
+    const raw = (typeof h['x-kova-covenant'] === 'string' ? h['x-kova-covenant'] : h['x-kova-covenant']?.[0]) ?? null;
+    if (raw)
+        return raw;
+    const auth = (typeof h['authorization'] === 'string' ? h['authorization'] : h['authorization']?.[0]) ?? '';
+    const bearer = auth.startsWith('Bearer ') ? auth.slice(7).trim() : null;
+    if (bearer) {
+        try {
+            return JSON.parse(Buffer.from(bearer, 'base64').toString('utf-8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Kova API Gateway middleware — requires agents to present a valid covenant before API access.
+ *
+ * Drop-in middleware for Express/Connect. Every agent calling the API must present
+ * a covenant (via `x-kova-covenant` header or `Authorization: Bearer <base64>`).
+ * The gateway verifies the covenant and evaluates the request. Protects API
+ * providers from liability when agents misuse their API.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { SteleClient, kovaGatewayMiddleware } from '@nobulex/sdk';
+ *
+ * const client = new SteleClient();
+ * const app = express();
+ *
+ * app.use(kovaGatewayMiddleware({ client }));
+ *
+ * app.get('/data', (req, res) => res.json({ data: 'allowed' }));
+ * ```
+ */
+export function kovaGatewayMiddleware(options) {
+    const { client, covenantExtractor = defaultCovenantExtractor, requiredConstraints, actionExtractor = defaultActionExtractor, resourceExtractor = defaultResourceExtractor, onDenied = defaultOnDenied, onError = defaultOnError, } = options;
+    return (req, res, next) => {
+        const raw = covenantExtractor(req);
+        if (!raw) {
+            if (res.setHeader)
+                res.setHeader('content-type', 'application/json');
+            if (res.statusCode !== undefined)
+                res.statusCode = 401;
+            if (res.end)
+                res.end(JSON.stringify({ error: 'Missing covenant. Send x-kova-covenant header or Authorization: Bearer <covenant-base64>' }));
+            return;
+        }
+        let covenant;
+        try {
+            covenant = typeof raw === 'string' ? deserializeCovenant(raw) : raw;
+        }
+        catch {
+            if (res.setHeader)
+                res.setHeader('content-type', 'application/json');
+            if (res.statusCode !== undefined)
+                res.statusCode = 401;
+            if (res.end)
+                res.end(JSON.stringify({ error: 'Invalid covenant format' }));
+            return;
+        }
+        void verifyCovenant(covenant).then((verifyResult) => {
+            if (!verifyResult.valid) {
+                if (res.setHeader)
+                    res.setHeader('content-type', 'application/json');
+                if (res.statusCode !== undefined)
+                    res.statusCode = 401;
+                if (res.end)
+                    res.end(JSON.stringify({ error: 'Covenant verification failed', details: verifyResult.checks.filter((c) => !c.passed) }));
+                return;
+            }
+            if (requiredConstraints && requiredConstraints.length > 0) {
+                const constraints = covenant.constraints ?? '';
+                const missing = requiredConstraints.filter((rc) => !constraints.includes(rc));
+                if (missing.length > 0) {
+                    if (res.setHeader)
+                        res.setHeader('content-type', 'application/json');
+                    if (res.statusCode !== undefined)
+                        res.statusCode = 401;
+                    if (res.end)
+                        res.end(JSON.stringify({ error: 'Covenant missing required constraints', missing }));
+                    return;
+                }
+            }
+            const action = actionExtractor(req);
+            const resource = resourceExtractor(req);
+            return client
+                .evaluateAction(covenant, action, resource)
+                .then((result) => {
+                if (result.permitted) {
+                    if (res.setHeader)
+                        res.setHeader('x-kova-permitted', 'true');
+                    next();
+                }
+                else {
+                    onDenied(req, res, result);
+                }
+            })
+                .catch((error) => {
+                onError(req, res, error);
+            });
+        });
+    };
+}
+//# sourceMappingURL=express.js.map