field-guard skill

field-guard is a lightweight, fully type-safe, field-level access control library for TypeScript with zero runtime dependencies.

Import

import { defineGuard, combineGuards, mergeFieldVerdicts } from "field-guard";

Define a Guard

type Ctx = { userId: string; role: "admin" | "user" };
type User = { id: string; email: string; name: string };

const userGuard = defineGuard<Ctx>()({
  fields: ["id", "email", "name"],
  policy: {
    owner: true,                     // all fields allowed
    admin: true,                     // all fields allowed
    other: { id: true, name: true }, // whitelist — only id and name
    banned: false,                   // no fields allowed
  },
});

Policy Modes

fields and policy are both optional. You can omit either or both.

.withCheck<Target>()

Resolves the access level based on context and a target object. Use verdictMap[level] to return the correct FieldVerdict.

const userGuard = defineGuard<Ctx>()({
  fields: ["id", "email", "name"],
  policy: {
    owner: true,
    other: { id: true, name: true },
  },
}).withCheck<User>()(({ ctx, target, verdictMap }) => {
  const level = ctx.userId === target.id ? "owner" : "other";
  return verdictMap[level];
});

// Evaluate
const g = userGuard.for({ userId: "1", role: "user" });
const verdict = g.check({ id: "1", email: "me@example.com", name: "Me" });
verdict.allowedFields; // ["id", "email", "name"]

.withDerive()

Computes extra properties from context. Can also produce row-level filter conditions.

import { eq } from "drizzle-orm";

type Post = { id: string; content: string; authorId: string };

const postGuard = defineGuard<Ctx>()({
  fields: ["id", "content", "authorId"],
  policy: {
    owner: true,
    other: { id: true, content: true },
  },
})
  .withDerive(({ ctx }) => ({
    // Row-level filter (e.g. for Drizzle ORM WHERE clause)
    where: ctx.role === "admin"
      ? undefined
      : eq(posts.authorId, ctx.userId),
  }))
  .withCheck<Post>()(({ ctx, target, verdictMap }) => {
    const level = ctx.userId === target.authorId ? "owner" : "other";
    return verdictMap[level];
  });

// Usage
const g = postGuard.for({ userId: "1", role: "user" });
const rows = await db.select().from(posts).where(g.where); // row-level
const results = rows.map((row) => g.check(row).pick(row)); // field-level

combineGuards

Bundles multiple guards for different resources and binds them all at once with a single .for() call.

const guards = combineGuards<Ctx>()({
  users: userGuard,
  posts: postGuard,
});

const g = guards.for({ userId: "1", role: "user" });

g.users.check({ id: "1", email: "a@b.com", name: "A" });
g.posts.check({ id: "p1", content: "hello", authorId: "1" });

FieldVerdict Helpers

verdict.allowedFields;              // string[] of allowed field names
verdict.coversAll(["id", "name"]);  // true if all given fields are allowed
verdict.coversSome(["email"]);      // true if any given field is allowed
verdict.pick(obj);                  // returns object with only allowed fields

mergeFieldVerdicts

Merges multiple verdicts with "union" (any-of) or "intersection" (all-of) strategy.

// Union: field allowed if ANY verdict allows it
mergeFieldVerdicts("union", [verdictA, verdictB], fields);

// Intersection: field allowed only if ALL verdicts allow it
mergeFieldVerdicts("intersection", [verdictA, verdictB], fields);

Also available as mergeVerdicts on every guard instance:

const verdict = guard.mergeVerdicts("union", { owner: true, admin: false });

Type Safety

All fields, levels, and verdicts are inferred from your definitions. The TypeScript compiler immediately flags:

• Unknown field names in policy
• Unknown levels in verdictMap lookups
• Incorrect return types from .withCheck()

Type errors from AI-generated code become instant feedback — no runtime surprises.