@suluk/hono 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/hono",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The Suluk derivation engine: minimal Hono+Zod RouteContracts in; v4 doc (dynamic per principal+time), validation, contract tests, and doc-coverage audit out. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"
@@ -19,7 +19,7 @@
 ".": "./src/index.ts"
 },
 "dependencies": {
-  "@suluk/core": "^0.1.7",
+  "@suluk/core": "^0.1.11",
   "@suluk/zod": "^0.1.2",
   "ajv": "^8.20.0",
   "ajv-formats": "^3.0.1"

package/src/access.ts

@@ -0,0 +1,67 @@
+/**
+ * The ROW-LEVEL authorization engine that pairs with {@link enforceAccess} (the wire-level facet enforcer). A
+ * generic CRUD app declares each entity's access MODE; this maps mode → per-operation Rule → a decision: may the
+ * caller run it, and is the query SCOPED to their own rows. Pure (no Hono Context — takes the resolved
+ * `{ isAdmin, principal }`), so it is testable and reusable. `ruleToRequires` projects a Rule to the wire
+ * `requires` level so ONE declaration drives BOTH the CRUD gate AND the `x-suluk-access` facet/docs.
+ */
+import type { AccessRequires } from "./enforce";
+
+/** A CRUD operation's authorization rule. */
+export type Rule = "any" | "owner" | "admin" | "none";
+/** The five CRUD operations' rules for one access mode. */
+export interface Policy { list: Rule; get: Rule; create: Rule; update: Rule; delete: Rule }
+/** The built-in access modes (a sensible SaaS/commerce default set; override via `policyFor`'s `policies` arg). */
+export type AccessMode = "public" | "admin" | "submit" | "owned" | "ownedAppend" | "ownedReadonly" | "review";
+
+/** The opt-in default mode→policy preset. Adopt by reference, or pass your own matrix to {@link policyFor}. */
+export const DEFAULT_POLICIES: Record<AccessMode, Policy> = {
+  // catalog + content: world-readable, admin-writable
+  public: { list: "any", get: "any", create: "admin", update: "admin", delete: "admin" },
+  // sensitive (e.g. discount codes): admin-only — even reads (listing all is a leak)
+  admin: { list: "admin", get: "admin", create: "admin", update: "admin", delete: "admin" },
+  // public submissions (contact, newsletter): anyone may create; only admins read/modify
+  submit: { list: "admin", get: "admin", create: "any", update: "admin", delete: "admin" },
+  // user-owned: each caller only sees/mutates their own rows (admin sees all)
+  owned: { list: "owner", get: "owner", create: "owner", update: "owner", delete: "owner" },
+  // owned + append-only to the user — place + read your own, but only the system/admin mutates (no self-mark-paid)
+  ownedAppend: { list: "owner", get: "owner", create: "owner", update: "admin", delete: "admin" },
+  // owned but READ-ONLY to the user — the system/admin even creates it (e.g. billing rows)
+  ownedReadonly: { list: "owner", get: "owner", create: "admin", update: "admin", delete: "admin" },
+  // public-read, owner-write (e.g. product reviews): everyone reads; you only edit your own
+  review: { list: "any", get: "any", create: "owner", update: "owner", delete: "owner" },
+};
+
+/** The policy for an access mode (default: owned when an ownerCol is present, else public). `policies` overrides the preset. */
+export function policyFor(access: AccessMode | undefined, ownerCol?: string, policies: Record<AccessMode, Policy> = DEFAULT_POLICIES): Policy {
+  return policies[access ?? (ownerCol ? "owned" : "public")];
+}
+
+/** The resolved caller identity a gate decision needs (compute from your Hono Context: isAdmin flag + principal id). */
+export interface GateIdentity { isAdmin: boolean; principal: string | null }
+/** A gate decision: may the op run, scope the query to the owner, and — when denied — the honest status. */
+export interface GateDecision { ok: boolean; scopeOwner: boolean; status?: 401 | 403 }
+
+/**
+ * Decide whether a caller may run an op (per the rule), whether to scope the query to their own rows, and the honest
+ * deny status. FAIL-CLOSED: an `owner` op with no principal is 401 (the wire must enforce what `x-suluk-access`
+ * claims — a null-scoped empty 200 would let the facet lie); `admin` with no principal is 401, signed-in-non-admin is
+ * 403; `none` hard-denies 403. A signed-in owner is scoped to their rows; an admin sees all.
+ */
+export function gate(rule: Rule, id: GateIdentity): GateDecision {
+  switch (rule) {
+    case "any": return { ok: true, scopeOwner: false };
+    case "owner":
+      if (id.isAdmin) return { ok: true, scopeOwner: false };                   // admin sees all
+      if (!id.principal) return { ok: false, scopeOwner: false, status: 401 };  // owner op needs a verified caller
+      return { ok: true, scopeOwner: true };                                    // signed-in: scoped to own rows
+    case "admin":
+      if (!id.principal) return { ok: false, scopeOwner: false, status: 401 };  // authenticate first (RFC 7235)
+      return id.isAdmin ? { ok: true, scopeOwner: false } : { ok: false, scopeOwner: false, status: 403 }; // signed-in non-admin → 403
+    default: return { ok: false, scopeOwner: false, status: 403 };
+  }
+}
+
+/** Project a CRUD Rule to the wire-level `requires` (so one rule drives BOTH the gate AND the x-suluk-access facet). */
+const RULE_TO_REQUIRES: Record<Rule, AccessRequires> = { any: "anyone", owner: "authenticated", admin: "admin", none: "admin" };
+export function ruleToRequires(rule: Rule): AccessRequires { return RULE_TO_REQUIRES[rule]; }

package/src/index.ts

@@ -10,6 +10,8 @@ export { contractChecks, runContractChecks, type Check, type CheckRun } from "./
 export { validateSchema2020, type SchemaCheck } from "./schema-check";
 export { mount } from "./mount";
 export { enforceAccess, createGuard, type EnforceAccessConfig, type IdentityConfig, type Guard, type AccessFacet, type AccessRequires } from "./enforce";
+// the row-level CRUD authorization engine (mode→policy→rule→decision + owner-scoping) that pairs with enforceAccess.
+export { gate, policyFor, ruleToRequires, DEFAULT_POLICIES, type Rule, type Policy, type AccessMode, type GateIdentity, type GateDecision } from "./access";
 export { SulukHttpError, HttpErrors, type SulukHttpErrorInit } from "./errors";
 export { onError, type OnErrorOptions } from "./on-error";
 export {

package/test/access.test.ts

@@ -0,0 +1,46 @@
+/**
+ * The row-level CRUD authorization engine — gate() decisions (fail-closed 401/403 + owner-scoping), policyFor
+ * preset resolution + override, and ruleToRequires (the rule→wire-requires projection that keeps the CRUD gate and
+ * the x-suluk-access facet in lockstep).
+ */
+import { test, expect, describe } from "bun:test";
+import { gate, policyFor, ruleToRequires, DEFAULT_POLICIES, type Rule } from "../src/index";
+
+describe("gate", () => {
+  test("any → open, no scope", () => {
+    expect(gate("any", { isAdmin: false, principal: null })).toEqual({ ok: true, scopeOwner: false });
+  });
+  test("owner: anon → 401, signed-in → scoped, admin → all", () => {
+    expect(gate("owner", { isAdmin: false, principal: null })).toEqual({ ok: false, scopeOwner: false, status: 401 });
+    expect(gate("owner", { isAdmin: false, principal: "u1" })).toEqual({ ok: true, scopeOwner: true });
+    expect(gate("owner", { isAdmin: true, principal: "u1" })).toEqual({ ok: true, scopeOwner: false }); // admin sees all
+  });
+  test("admin: anon → 401 (authenticate first), signed-in-non-admin → 403, admin → ok", () => {
+    expect(gate("admin", { isAdmin: false, principal: null })).toEqual({ ok: false, scopeOwner: false, status: 401 });
+    expect(gate("admin", { isAdmin: false, principal: "u1" })).toEqual({ ok: false, scopeOwner: false, status: 403 });
+    expect(gate("admin", { isAdmin: true, principal: "u1" })).toEqual({ ok: true, scopeOwner: false });
+  });
+  test("none → hard 403", () => {
+    expect(gate("none", { isAdmin: true, principal: "u1" })).toEqual({ ok: false, scopeOwner: false, status: 403 });
+  });
+});
+
+describe("policyFor", () => {
+  test("resolves modes, defaults owned-with-ownerCol / public-without, honors an override matrix", () => {
+    expect(policyFor("owned").update).toBe("owner");
+    expect(policyFor("ownedAppend").update).toBe("admin"); // no self-mutate
+    expect(policyFor(undefined, "customerId")).toEqual(DEFAULT_POLICIES.owned);
+    expect(policyFor(undefined)).toEqual(DEFAULT_POLICIES.public);
+    const custom = { ...DEFAULT_POLICIES, public: { ...DEFAULT_POLICIES.public, list: "admin" as Rule } };
+    expect(policyFor("public", undefined, custom).list).toBe("admin");
+  });
+});
+
+describe("ruleToRequires", () => {
+  test("projects a CRUD rule to the wire requires level", () => {
+    expect(ruleToRequires("any")).toBe("anyone");
+    expect(ruleToRequires("owner")).toBe("authenticated");
+    expect(ruleToRequires("admin")).toBe("admin");
+    expect(ruleToRequires("none")).toBe("admin");
+  });
+});