@spfn/core 0.2.0-beta.9 → 0.3.0-beta.2

package/dist/authz/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @spfn/core/authz - Authorization primitives
+ *
+ * Small, domain-agnostic guards for resource ownership. The point is to make the
+ * "load, then check it belongs to the requester" step a single call so a handler
+ * can't forget it and leak another user's data (IDOR).
+ */
+interface RequireOwnerOptions<T> {
+    /**
+     * Property on the resource holding the owner id. Defaults to `'ownerId'`.
+     * SPFN entities commonly use `userId` / `createdBy` — pass it explicitly:
+     * `requireOwner(doc, userId, { ownerKey: 'userId' })`.
+     */
+    ownerKey?: keyof T;
+    /** Message for the thrown NotFoundError. @default 'not found' */
+    message?: string;
+}
+/**
+ * Return the resource only if it exists and belongs to `ownerId`; otherwise throw
+ * `NotFoundError`. Not-found and not-owned are deliberately the same response, so
+ * the endpoint never reveals that a resource exists to a non-owner.
+ *
+ * Ids are compared as strings, so number/string/bigint ids interoperate. A
+ * missing or null owner value never matches, so it throws.
+ *
+ * @example
+ * ```ts
+ * const chat = requireOwner(await chats.findById(id), userId, { ownerKey: 'userId' });
+ * // chat is non-null here, narrowed from T | null
+ * ```
+ */
+declare function requireOwner<T extends object>(resource: T | null | undefined, ownerId: string | number | bigint, options?: RequireOwnerOptions<T>): T;
+
+export { type RequireOwnerOptions, requireOwner };