permdock 0.0.0 → 0.1.0

package/dist/nest/index.d.ts

@@ -0,0 +1,80 @@
+import { $ as DecisionSink, C as Policy, Zt as PermDock, at as LimitStore, ct as MembershipSource, ft as RelationSource, mr as Principal, pt as RoleSource, sn as PolicySource, tt as EntitlementSource, xt as SnapshotSource } from "../policy-CInmNGkM.js";
+import { d as Permission } from "../permissions-B4apnahQ.js";
+import { f as ApprovalStore } from "../types-B8w5PFtS.js";
+import { n as RevocationFeed } from "../revocations-Cy06JNx2.js";
+import { o as OtelWrap } from "../types-B9dmiiab.js";
+import { r as PdpFactory } from "../types-BvBk1wgn.js";
+import { S as ConnectionOptions, b as Connection, g as discoverViaSignatureAgent, h as WebBotAuthVerifier, n as OpenApiHooks, o as TenantOption, r as ProtectOptions, u as InvalidSignatureError, y as verifyWebBotAuth } from "../create-BKF3dgFk.js";
+import { i as sendResponse, t as NodeRequest } from "../http-DPuDaChb.js";
+import { CanActivate, ExceptionFilter, ExecutionContext, Type } from "@nestjs/common";
+//#region src/nest/http.d.ts
+/**
+ * `@nestjs/platform-express` hands the guard an `IncomingMessage`;
+ * `@nestjs/platform-fastify` hands it a `FastifyRequest` whose stream is `raw`.
+ */
+export declare function toRequest(req: NodeRequest): Request;
+//#endregion
+//#region src/nest/create.d.ts
+type NestRequest = NodeRequest & {
+  readonly params?: Readonly<Record<string, string>>;
+  permdock?: PermDock;
+  permdockData?: unknown;
+};
+type NestPermDockOptions<TUser = unknown> = {
+  readonly subject: (req: NestRequest) => TUser | Promise<TUser>;
+  readonly tenant?: TenantOption<NestRequest>;
+  readonly memberships?: MembershipSource | readonly MembershipSource[];
+  /** The object graph for relation grants that walk a parent chain; without it they deny. */
+  readonly relations?: RelationSource;
+  readonly entitlements?: EntitlementSource;
+  readonly customRoles?: RoleSource;
+  /** Hosted grants, read once per instance; see `PolicySource`. */
+  readonly policies?: PolicySource;
+  readonly store?: ApprovalStore;
+  readonly sink?: DecisionSink;
+  readonly limits?: LimitStore;
+  /** `createPermDock` from `permdock/pdp`; `protect` then decides delegated permissions remotely. */
+  readonly pdp?: PdpFactory;
+  /** Accepted for adapter parity; not read by this adapter. */
+  readonly snapshots?: SnapshotSource;
+  /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
+  readonly otel?: OtelWrap;
+  /** `(request) => verifyWebBotAuth(request, options)`; a verified bot becomes the actor. */
+  readonly webBotAuth?: WebBotAuthVerifier;
+  /**
+   * Maps a `ws`, `rpc` or `graphql` context to the request its subject comes
+   * from. Without it, a protected handler outside HTTP is denied.
+   */
+  readonly request?: (context: ExecutionContext) => NestRequest | undefined;
+  /** Ends or revalidates open gateway connections. */
+  readonly revocations?: RevocationFeed;
+};
+/** A gateway client: Socket.IO (`emit`, `disconnect`) or `ws` (`close`). */
+type NestSocket = {
+  emit?(event: string, payload: unknown): unknown;
+  disconnect?(close?: boolean): unknown;
+  close?(code?: number, reason?: string): unknown;
+};
+type NestProtect = (permission: Permission, loadData?: (req: NestRequest) => unknown, protectOptions?: ProtectOptions) => ClassDecorator & MethodDecorator;
+type NestHandlerOptions = {
+  /** Controller path; may hold route params such as `:org`. Default `api/permdock`. */
+  readonly path?: string;
+};
+type NestPermDock = {
+  readonly PermDockModule: Type<unknown>;
+  readonly PermDockGuard: Type<CanActivate>;
+  readonly Protect: NestProtect;
+  readonly InjectPermDock: () => ParameterDecorator;
+  readonly PermDockExceptionFilter: Type<ExceptionFilter>;
+  readonly permdockHandler: (options?: NestHandlerOptions) => Type<unknown>;
+  /**
+   * Opens the connection for a gateway client in `handleConnection`, from the
+   * handshake request. `Protect` rules on that client's messages then decide
+   * against the connection's current instance.
+   */
+  readonly connection: (client: NestSocket, req: NestRequest, connectionOptions?: ConnectionOptions) => Promise<Connection>;
+  readonly openapi: OpenApiHooks;
+};
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: NestPermDockOptions<TUser>): NestPermDock;
+//#endregion
+export { InvalidSignatureError, type NestHandlerOptions, type NestPermDock, type NestPermDockOptions, type NestProtect, type NestRequest, type NestSocket, discoverViaSignatureAgent, sendResponse, verifyWebBotAuth };

package/dist/nest/index.js

@@ -0,0 +1,270 @@
+import { t as compact } from "../compact-y6vfu2_f.js";
+import { i as PermDockValidationError, n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-Iy71s7Oj.js";
+import { i as discoverViaSignatureAgent, r as InvalidSignatureError, s as verifyWebBotAuth } from "../evaluations-DsAU9ppl.js";
+import { r as tenantScope, t as createKernel } from "../create-CSkhDU9T.js";
+import { t as problemFromError } from "../map-error-RJ3ZsUyA.js";
+import { i as onRevoked, t as POLICY_VIOLATION } from "../stream-Q_xlB6Ko.js";
+import { i as toRequest$1, n as isServerResponse, r as sendResponse } from "../http-GgVApX1k.js";
+import { Catch, Controller, Get, Inject, Injectable, Module, Post, Req, Res, createParamDecorator } from "@nestjs/common";
+import { APP_FILTER, Reflector } from "@nestjs/core";
+//#region src/nest/http.ts
+function isReadable(value) {
+	return typeof value === "object" && value !== null && typeof value.read === "function";
+}
+function isFastifyReply(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const reply = value;
+	return typeof reply["code"] === "function" && typeof reply["header"] === "function" && typeof reply["send"] === "function";
+}
+/**
+* `@nestjs/platform-express` hands the guard an `IncomingMessage`;
+* `@nestjs/platform-fastify` hands it a `FastifyRequest` whose stream is `raw`.
+*/
+function toRequest(req) {
+	if (isReadable(req)) return toRequest$1(req);
+	const raw = req.raw;
+	return toRequest$1(req, isReadable(raw) ? raw : null);
+}
+async function sendNestResponse(res, response) {
+	if (isServerResponse(res)) {
+		await sendResponse(res, response);
+		return;
+	}
+	if (isFastifyReply(res)) {
+		res.code(response.status);
+		for (const [key, value] of response.headers.entries()) res.header(key, value);
+		await res.send(await response.text());
+		return;
+	}
+	throw new TypeError("permdock/nest supports @nestjs/platform-express and @nestjs/platform-fastify responses");
+}
+//#endregion
+//#region src/nest/create.ts
+const PROTECT_KEY = "permdock:protect";
+var PermDockHttpError = class extends Error {
+	name = "PermDockHttpError";
+	response;
+	constructor(response) {
+		super("permdock denied");
+		this.response = response;
+	}
+};
+function reflectMeta() {
+	const ref = Reflect;
+	if (typeof ref.getMetadata !== "function" || typeof ref.defineMetadata !== "function") throw new TypeError("reflect-metadata is required for permdock/nest");
+	return ref;
+}
+function applyMethod(cls, key, decorator) {
+	const descriptor = Object.getOwnPropertyDescriptor(cls.prototype, key);
+	if (descriptor === void 0) throw new TypeError(`missing ${key} handler`);
+	decorator(cls.prototype, key, descriptor);
+}
+function applyParameter(cls, key, index, decorator) {
+	decorator(cls.prototype, key, index);
+}
+function hasEmit(value) {
+	return typeof value === "object" && value !== null && typeof value.emit === "function";
+}
+function rulesOf(target) {
+	const found = reflectMeta().getMetadata(PROTECT_KEY, target);
+	if (!Array.isArray(found)) return [];
+	return found;
+}
+const Protect = (permission, loadData, protectOptions) => {
+	const rule = compact({
+		permission,
+		loadData,
+		options: protectOptions
+	});
+	return ((target, _propertyKey, descriptor) => {
+		const store = descriptor === void 0 ? target : descriptor.value;
+		if (typeof store !== "function" && (typeof store !== "object" || store === null)) throw new TypeError("Protect requires a class or method");
+		const existing = rulesOf(store);
+		reflectMeta().defineMetadata(PROTECT_KEY, [...existing, rule], store);
+	});
+};
+function createPermDock(policy, options) {
+	const contexts = /* @__PURE__ */ new WeakMap();
+	const bound = /* @__PURE__ */ new WeakMap();
+	const kernel = createKernel(policy, compact({
+		subject: (request) => {
+			const req = contexts.get(request);
+			return req === void 0 ? null : options.subject(req);
+		},
+		memberships: options.memberships,
+		relations: options.relations,
+		entitlements: options.entitlements,
+		customRoles: options.customRoles,
+		policies: options.policies,
+		store: options.store,
+		sink: options.sink,
+		limits: options.limits,
+		pdp: options.pdp,
+		webBotAuth: options.webBotAuth,
+		revocations: options.revocations,
+		adapter: "nest",
+		wrap: options.otel
+	}));
+	const scopeOf = (req) => tenantScope(options.tenant, req);
+	const applyProtect = async (remaining, req, request, scope) => {
+		const [rule, ...rest] = remaining;
+		if (rule === void 0) return;
+		const loader = rule.loadData;
+		const guard = await kernel.protect(rule.permission, loader === void 0 ? void 0 : () => loader(req), rule.options)(request, scope);
+		if (!guard.ok) throw new PermDockHttpError(guard.response);
+		req.permdock = guard.permdock;
+		req.permdockData = guard.data;
+		await applyProtect(rest, req, request, scope);
+	};
+	const bind = (req) => {
+		const hit = bound.get(req);
+		if (hit !== void 0) return hit;
+		const request = toRequest(req);
+		bound.set(req, request);
+		contexts.set(request, req);
+		return request;
+	};
+	const sockets = /* @__PURE__ */ new WeakMap();
+	const connection = (client, req, connectionOptions) => {
+		const hit = sockets.get(client);
+		if (hit !== void 0) return hit;
+		const opened = (async () => {
+			const conn = await kernel.connection(bind(req), connectionOptions, await scopeOf(req));
+			onRevoked(conn, (problem) => {
+				client.emit?.("permdock:error", problem);
+				if (typeof client.disconnect === "function") client.disconnect(true);
+				else client.close?.(POLICY_VIOLATION, problem.type);
+			});
+			return conn;
+		})();
+		sockets.set(client, opened);
+		return opened;
+	};
+	/** Decides each rule for a gateway message against the client's connection. */
+	const checkMessage = async (rules, conn, req) => {
+		for (const rule of rules) {
+			const loader = rule.loadData;
+			let data;
+			if (loader !== void 0) {
+				data = req === void 0 ? void 0 : await loader(req);
+				if (data === null || data === void 0) throw new PermDockHttpError(new Response(null, { status: 404 }));
+			}
+			const decision = conn.check(rule.permission, data, rule.options?.trusted === true ? { trusted: true } : void 0);
+			if (decision.outcome !== "granted") throw new PermDockHttpError(kernel.problem(decision, { permission: rule.permission }));
+		}
+	};
+	class PermDockGuard {
+		reflector;
+		constructor(reflector) {
+			this.reflector = reflector;
+		}
+		async canActivate(context) {
+			const rules = this.rulesFor(context);
+			if (context.getType() === "ws" && rules.length > 0) {
+				const opened = sockets.get(context.switchToWs().getClient());
+				if (opened !== void 0) {
+					await checkMessage(rules, await opened, options.request?.(context));
+					return true;
+				}
+			}
+			const req = context.getType() === "http" ? context.switchToHttp().getRequest() : rules.length === 0 ? void 0 : options.request?.(context);
+			if (req === void 0) return rules.length === 0;
+			const request = bind(req);
+			const scope = await scopeOf(req);
+			req.permdock = await kernel.permdock(request, scope);
+			await applyProtect(rules, req, request, scope);
+			return true;
+		}
+		rulesFor(context) {
+			const fromClass = this.reflector.get(PROTECT_KEY, context.getClass());
+			const fromHandler = this.reflector.get(PROTECT_KEY, context.getHandler());
+			return [...Array.isArray(fromClass) ? fromClass : rulesOf(context.getClass()), ...Array.isArray(fromHandler) ? fromHandler : rulesOf(context.getHandler())];
+		}
+	}
+	Inject(Reflector)(PermDockGuard, void 0, 0);
+	Injectable()(PermDockGuard);
+	class PermDockExceptionFilter {
+		send = sendNestResponse;
+		async catch(exception, host) {
+			const problem = exception instanceof PermDockHttpError ? exception.response : problemFromError(exception);
+			if (problem === void 0) throw new TypeError("unhandled permdock exception");
+			if (host.getType() === "http") {
+				await this.send(host.switchToHttp().getResponse(), problem);
+				return;
+			}
+			const client = host.getType() === "ws" ? host.switchToWs().getClient() : null;
+			if (!hasEmit(client)) throw exception;
+			const body = await problem.json();
+			client.emit("exception", {
+				status: "error",
+				message: typeof body.title === "string" ? body.title : "Forbidden",
+				problem: body
+			});
+		}
+	}
+	Catch(PermDockHttpError, InvalidSignatureError, PermDockDeniedError, PermDockApprovalRequiredError, PermDockValidationError)(PermDockExceptionFilter);
+	Injectable()(PermDockExceptionFilter);
+	class PermDockRoot {
+		static adapter = "nest";
+	}
+	Module({
+		providers: [
+			{
+				provide: PermDockGuard,
+				useFactory: (reflector) => new PermDockGuard(reflector),
+				inject: [Reflector]
+			},
+			{
+				provide: PermDockExceptionFilter,
+				useFactory: () => new PermDockExceptionFilter()
+			},
+			{
+				provide: APP_FILTER,
+				useExisting: PermDockExceptionFilter
+			}
+		],
+		exports: [PermDockGuard, PermDockExceptionFilter]
+	})(PermDockRoot);
+	const injectPermDock = createParamDecorator((_data, ctx) => {
+		if (ctx.getType() !== "http") return;
+		return ctx.switchToHttp().getRequest().permdock;
+	});
+	const InjectPermDock = () => injectPermDock();
+	const permdockHandler = (handlerOptions = {}) => {
+		const { POST, GET } = kernel.permdockHandler((request) => {
+			const req = contexts.get(request);
+			return req === void 0 ? { tenant: void 0 } : scopeOf(req);
+		});
+		class EvaluationsController {
+			send = sendNestResponse;
+			async post(req, res) {
+				const request = toRequest(req);
+				contexts.set(request, req);
+				await this.send(res, await POST(request));
+			}
+			async get(req, res) {
+				await this.send(res, await GET(bind(req)));
+			}
+		}
+		Controller(handlerOptions.path ?? "api/permdock")(EvaluationsController);
+		applyMethod(EvaluationsController, "post", Post());
+		applyMethod(EvaluationsController, "get", Get());
+		applyParameter(EvaluationsController, "post", 0, Req());
+		applyParameter(EvaluationsController, "post", 1, Res({ passthrough: false }));
+		applyParameter(EvaluationsController, "get", 0, Req());
+		applyParameter(EvaluationsController, "get", 1, Res({ passthrough: false }));
+		return EvaluationsController;
+	};
+	return {
+		PermDockModule: PermDockRoot,
+		PermDockGuard,
+		Protect,
+		InjectPermDock,
+		PermDockExceptionFilter,
+		permdockHandler,
+		connection,
+		openapi: kernel.openapi
+	};
+}
+//#endregion
+export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, sendResponse, toRequest, verifyWebBotAuth };

package/dist/next/client.d.ts

@@ -0,0 +1,24 @@
+import { t as PermDockDigest } from "../digest-B3kc_PgQ.js";
+import { ComponentType, ReactNode } from "react";
+//#region src/next/client.d.ts
+export type PermissionBoundaryState = PermDockDigest & {
+  /** Re-fetches and re-renders the boundary's children, e.g. after an approval or a role change. */
+  readonly retry: () => void;
+};
+export type PermissionBoundaryProps = {
+  /** Rendered in place of the children when one throws `PermDockDeniedError`. */
+  readonly denied?: ReactNode;
+  /** Rendered when a child throws `PermDockApprovalRequiredError`; defaults to `denied`. */
+  readonly approval?: ReactNode;
+};
+/**
+ * A component-level boundary for PermDock errors thrown below it, in a Server
+ * Component or a Client Component. Other errors, `forbidden()`, `notFound()`
+ * and `redirect()` pass through.
+ */
+export declare const PermissionBoundary: ComponentType<PermissionBoundaryProps & {
+  readonly children?: ReactNode;
+}>;
+/** Inside a `PermissionBoundary` fallback: what was refused, and `retry()`. */
+export declare function usePermissionBoundary(): PermissionBoundaryState | null;
+//#endregion

package/dist/next/client.js

@@ -0,0 +1,31 @@
+"use client";
+import { r as parsePermDockDigest } from "../digest-BI-6aa6d.js";
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+import { catchError } from "next/error";
+//#region src/next/client.tsx
+const BoundaryContext = createContext(null);
+function PermissionFallback(props, info) {
+	const parsed = parsePermDockDigest(info.error.digest);
+	if (parsed === null) throw info.error;
+	const node = parsed.outcome === "approval-required" ? props.approval ?? props.denied : props.denied;
+	return /* @__PURE__ */ jsx(BoundaryContext.Provider, {
+		value: {
+			...parsed,
+			retry: info.retry
+		},
+		children: node ?? null
+	});
+}
+/**
+* A component-level boundary for PermDock errors thrown below it, in a Server
+* Component or a Client Component. Other errors, `forbidden()`, `notFound()`
+* and `redirect()` pass through.
+*/
+const PermissionBoundary = catchError(PermissionFallback);
+/** Inside a `PermissionBoundary` fallback: what was refused, and `retry()`. */
+function usePermissionBoundary() {
+	return useContext(BoundaryContext);
+}
+//#endregion
+export { PermissionBoundary, usePermissionBoundary };

package/dist/next/index.d.ts

@@ -0,0 +1,110 @@
+import { $ as DecisionSink, C as Policy, E as PolicyVocabulary, Mn as Decision, Zt as PermDock, at as LimitStore, ct as MembershipSource, ft as RelationSource, mr as Principal, pt as RoleSource, sn as PolicySource, tt as EntitlementSource, xt as SnapshotSource } from "../policy-CInmNGkM.js";
+import { d as Permission } from "../permissions-B4apnahQ.js";
+import { f as ApprovalStore } from "../types-B8w5PFtS.js";
+import { o as OtelWrap } from "../types-B9dmiiab.js";
+import { ReactElement, ReactNode } from "react";
+//#region src/next/cache-life.d.ts
+type CacheLifeForOptions = {
+  /** Lower bound in seconds. Next.js includes a private entry in per-link prefetches from 30. */
+  readonly min?: number;
+  /** Upper bound in seconds. Next.js keeps a per-session App Shell entry from 300. */
+  readonly max?: number;
+  /** Seconds since the epoch; defaults to the snapshot's `issuedAt`, then the clock. */
+  readonly now?: number;
+};
+/**
+ * `{ stale }` for `cacheLife()` inside an app-owned `'use cache: private'` function: `max` when the
+ * value never expires, otherwise the seconds left, clamped to `[min, max]`. A value with less than
+ * `min` seconds left gets its real remainder, so Next.js leaves it out of prefetches instead of
+ * serving it past `expiresAt`.
+ */
+export declare function cacheLifeFor(value: {
+  readonly expiresAt?: number | null;
+  readonly issuedAt?: number;
+} | null, options?: CacheLifeForOptions): {
+  readonly stale: number;
+};
+//#endregion
+//#region src/next/types.d.ts
+type NextSubjectInput = unknown;
+type NextPermDockOptions<TUser = NextSubjectInput> = {
+  readonly subject: () => TUser | Promise<TUser>;
+  readonly tenant?: string | (() => string | undefined | Promise<string | undefined>);
+  readonly onDenied?: (decision: Decision) => never | void;
+  readonly memberships?: MembershipSource | readonly MembershipSource[];
+  /** The object graph for relation grants that walk a parent chain; without it they deny. */
+  readonly relations?: RelationSource;
+  readonly entitlements?: EntitlementSource;
+  readonly customRoles?: RoleSource;
+  /** Hosted grants, read once per instance; see `PolicySource`. */
+  readonly policies?: PolicySource;
+  readonly store?: ApprovalStore;
+  readonly sink?: DecisionSink;
+  readonly limits?: LimitStore;
+  readonly snapshots?: SnapshotSource;
+  /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
+  readonly otel?: OtelWrap;
+  /**
+   * Where `PermDockProvider` sends checks the snapshot cannot answer; default `/api/permdock`.
+   * `false` is snapshot-only: no `permdockHandler` route, and those checks are denied with
+   * reason `server-only`.
+   */
+  readonly endpoint?: string | false;
+};
+type GetPermDockQuery = {
+  readonly tenant?: string;
+};
+type RequireAccessInput = {
+  readonly permission: Permission;
+  /** The row for an instance permission; omit it for a collection permission. */
+  readonly data?: unknown;
+  /** The active tenant, as for `getPermDock({ tenant })`; defaults to the factory's `tenant`. */
+  readonly tenant?: string;
+};
+type ServerPermissionState = {
+  readonly allowed: boolean;
+  readonly status: "ready";
+  readonly decision: Decision;
+};
+type ServerPermDockProviderProps = {
+  readonly children: ReactNode;
+  readonly tenant?: string;
+  readonly include?: readonly (Permission | {
+    readonly [key: string]: unknown;
+  })[];
+  readonly tenants?: "all";
+  /** Overrides the factory's `endpoint`; `false` is snapshot-only. */
+  readonly endpoint?: string | false;
+};
+type PermDockHandler = {
+  readonly POST: (request: Request) => Promise<Response>;
+  readonly GET: (request: Request) => Promise<Response>;
+};
+type NextPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+  readonly getPermDock: (query?: GetPermDockQuery) => Promise<PermDock<V>>;
+  readonly getPermission: (permission: Permission, data?: unknown) => Promise<ServerPermissionState>;
+  /**
+   * Resolves to the granted `Decision`. A denial calls `unauthorized()` for an
+   * anonymous subject and `forbidden()` otherwise (`experimental.authInterrupts`);
+   * approval-required and boundary validation throw as from `assert`.
+   */
+  readonly requireAccess: (input: RequireAccessInput) => Promise<Extract<Decision, {
+    readonly outcome: "granted";
+  }>>;
+  /** Never awaits: passes an unawaited snapshot to the client provider, whose hooks suspend. */
+  readonly PermDockProvider: (props: ServerPermDockProviderProps) => ReactElement;
+  readonly permdockHandler: () => PermDockHandler;
+};
+//#endregion
+//#region src/next/create.d.ts
+export declare function createPermDock<TUser = NextSubjectInput, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: NextPermDockOptions<TUser>): NextPermDock<V>;
+//#endregion
+//#region src/next/snapshot-tag.d.ts
+/**
+ * The `cacheTag` for one subject's cached snapshots: `permdock:<sub>`, or `permdock:anon`
+ * without a subject. Tag the private cache with it and pass it to `updateTag` or
+ * `revalidateTag` on every write that changes the subject's snapshot.
+ */
+export declare function snapshotTag(sub?: string | null): string;
+//#endregion
+export type { CacheLifeForOptions, GetPermDockQuery, NextPermDock, NextPermDockOptions, PermDockHandler, RequireAccessInput, ServerPermDockProviderProps, ServerPermissionState };