@bajustone/fortress 1.0.0-rc.1

package/src/core/http/token-extraction.ts

@@ -0,0 +1,53 @@
+/**
+ * Token extraction from a web-standard Request.
+ *
+ * Reads the access token from the configured cookie first, then falls back
+ * to the `Authorization: Bearer` header. Pure function — no side effects,
+ * no framework dependencies.
+ */
+
+import type { ResolvedCookieConfig } from '../config';
+import { parseCookieHeader } from './cookie-serialize';
+
+/**
+ * Extract the access token from a request, preferring the
+ * `Authorization: Bearer <token>` header and falling back to the cookie
+ * configured via {@link ResolvedCookieConfig.accessName}.
+ *
+ * P3.7 fix: the previous implementation read the cookie first, which on a
+ * shared cookie domain could let a same-origin attacker's cookie shadow
+ * the caller's intended bearer token. The Authorization header is an
+ * explicit, intentional credential and takes precedence; the cookie is
+ * only consulted when no bearer header is present.
+ *
+ * Returns `null` if neither source carries a token.
+ */
+export function extractAccessToken(
+  request: Request,
+  cookies: ResolvedCookieConfig,
+): string | null {
+  const auth = request.headers.get('authorization');
+  if (auth) {
+    const separator = auth.indexOf(' ');
+    if (separator > 0 && auth.slice(0, separator).toLowerCase() === 'bearer') {
+      const fromHeader = auth.slice(separator + 1).trim();
+      if (fromHeader)
+        return fromHeader;
+    }
+  }
+
+  const jar = parseCookieHeader(request.headers.get('cookie'));
+  return jar[cookies.accessName] ?? null;
+}
+
+/**
+ * Extract the refresh token from a request's cookie jar. Refresh tokens are
+ * never read from headers — they live in `httpOnly` cookies only.
+ */
+export function extractRefreshToken(
+  request: Request,
+  cookies: ResolvedCookieConfig,
+): string | null {
+  const jar = parseCookieHeader(request.headers.get('cookie'));
+  return jar[cookies.refreshName] ?? null;
+}

package/src/core/iam/explain.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Tests for `explainPermission` (P1-8 operator-debugging helper).
+ */
+
+import { describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+import { explainPermission } from './explain';
+
+const SECRET = 'explain-test-secret-at-least-32-bytes!';
+
+function setup(evaluationMode: 'allow-only' | 'deny-overrides' = 'allow-only') {
+  const fortress = createFortress({
+    jwt: { key: SECRET },
+    database: createTestAdapter(),
+    rbac: { evaluationMode },
+  });
+  return { fortress };
+}
+
+describe('explainPermission', () => {
+  it('returns allowed=false with no sources for a user with no bindings', async () => {
+    const { fortress } = setup();
+    const user = await fortress.auth.createUser({
+      email: 'noperm@example.com',
+      name: 'Noperm',
+      password: 'noperm-password-1234564',
+    });
+    const result = await explainPermission(
+      fortress.config.database,
+      fortress.iam,
+      { type: 'USER', id: user.id },
+      'article',
+      'read',
+    );
+    expect(result.allowed).toBe(false);
+    expect(result.sources).toEqual([]);
+    expect(result.roleBindings).toEqual([]);
+    expect(result.groupMemberships).toEqual([]);
+  });
+
+  it('attributes a permission granted via a role binding', async () => {
+    const { fortress } = setup();
+    const user = await fortress.auth.createUser({
+      email: 'role@example.com',
+      name: 'Role User',
+      password: 'role-password-1234564',
+    });
+    const role = await fortress.iam.createRole('editor', [
+      { resource: 'article', action: 'create' },
+      { resource: 'article', action: 'update' },
+    ]);
+    await fortress.iam.bindRoleToUser(user.id, role.id);
+
+    const explain = await explainPermission(
+      fortress.config.database,
+      fortress.iam,
+      { type: 'USER', id: user.id },
+      'article',
+      'create',
+    );
+    expect(explain.allowed).toBe(true);
+    expect(explain.sources).toHaveLength(1);
+    expect(explain.sources[0].via).toBe('role');
+    expect(explain.sources[0].role).toBe('editor');
+    expect(explain.sources[0].permission.resource).toBe('article');
+    expect(explain.sources[0].permission.action).toBe('create');
+    expect(explain.roleBindings.map(rb => rb.role)).toEqual(['editor']);
+  });
+
+  it('attributes a permission granted via a direct binding', async () => {
+    const { fortress } = setup();
+    const user = await fortress.auth.createUser({
+      email: 'direct@example.com',
+      name: 'Direct',
+      password: 'direct-password-1234564',
+    });
+    await fortress.iam.bindPermissionToUser(user.id, { resource: 'article', action: 'publish' });
+
+    const explain = await explainPermission(
+      fortress.config.database,
+      fortress.iam,
+      { type: 'USER', id: user.id },
+      'article',
+      'publish',
+    );
+    expect(explain.allowed).toBe(true);
+    expect(explain.sources).toHaveLength(1);
+    expect(explain.sources[0].via).toBe('direct-user');
+  });
+
+  it('attributes a permission inherited via a group role binding', async () => {
+    const { fortress } = setup();
+    const user = await fortress.auth.createUser({
+      email: 'group@example.com',
+      name: 'Group',
+      password: 'group-password-1234564',
+    });
+    const group = await fortress.iam.createGroup('eng', 'Engineering');
+    await fortress.iam.addUserToGroup(group.id, user.id);
+    const role = await fortress.iam.createRole('viewer', [
+      { resource: 'article', action: 'read' },
+    ]);
+    await fortress.iam.bindRoleToGroup(group.id, role.id);
+
+    const explain = await explainPermission(
+      fortress.config.database,
+      fortress.iam,
+      { type: 'USER', id: user.id },
+      'article',
+      'read',
+    );
+    expect(explain.allowed).toBe(true);
+    expect(explain.sources).toHaveLength(1);
+    expect(explain.sources[0].via).toBe('role');
+    expect(explain.sources[0].role).toBe('viewer');
+    expect(explain.sources[0].group).toEqual({ id: group.id, name: 'eng' });
+    expect(explain.groupMemberships).toEqual([{ id: group.id, name: 'eng' }]);
+  });
+
+  it('uses the same condition context as checkPermission', async () => {
+    const { fortress } = setup();
+    const user = await fortress.auth.createUser({
+      email: 'condition@example.com',
+      name: 'Condition',
+      password: 'condition-password-1234564',
+    });
+    const role = await fortress.iam.createRole('owner', [{
+      resource: 'article',
+      action: 'edit',
+      conditions: [{ field: 'resource.ownerId', operator: 'eq', value: { ref: 'user.id' } }],
+    }]);
+    await fortress.iam.bindRoleToUser(user.id, role.id);
+
+    const explanation = await explainPermission(
+      fortress.config.database,
+      fortress.iam,
+      { type: 'USER', id: user.id },
+      'article',
+      'edit',
+      { resource: { ownerId: 'someone-else' } },
+    );
+    expect(explanation.sources).toHaveLength(0);
+    expect(explanation.allowed).toBe(false);
+  });
+
+  it('uses the configured deny-overrides evaluator', async () => {
+    const { fortress } = setup('deny-overrides');
+    const user = await fortress.auth.createUser({
+      email: 'deny@example.com',
+      name: 'Deny',
+      password: 'deny-password-1234564',
+    });
+    const allowRole = await fortress.iam.createRole('allow-articles', [
+      { resource: 'article', action: 'delete' },
+    ]);
+    await fortress.iam.bindRoleToUser(user.id, allowRole.id);
+    // Direct DENY overrides the role grant.
+    await fortress.iam.bindPermissionToUser(user.id, {
+      resource: 'article',
+      action: 'delete',
+      effect: 'DENY',
+    });
+
+    const explain = await explainPermission(
+      fortress.config.database,
+      fortress.iam,
+      { type: 'USER', id: user.id },
+      'article',
+      'delete',
+    );
+    expect(explain.allowed).toBe(false);
+    expect(explain.sources.length).toBeGreaterThanOrEqual(2);
+    expect(explain.sources.some(s => s.permission.effect === 'DENY')).toBe(true);
+    expect(explain.sources.some(s => (s.permission.effect ?? 'ALLOW') === 'ALLOW')).toBe(true);
+  });
+});

package/src/core/iam/explain.ts

@@ -0,0 +1,302 @@
+/**
+ * Permission debugging helper (P1-8).
+ *
+ * Answers the operator-console question "why does subject X have (or not
+ * have) permission `resource:action`?" by walking the same data the
+ * permission evaluator uses — direct bindings, role bindings, group
+ * memberships (for USER subjects) — and emitting a structured
+ * explanation listing every grant + its source.
+ *
+ * Designed as a free function rather than a new {@link IamService} method
+ * to keep the surface narrow and the DB queries explicit.
+ *
+ * @module
+ */
+
+import type { DatabaseAdapter } from '../../adapters/database';
+import type { Permission, PermissionContext, Role, Subject } from '../types';
+import type { IamService } from './iam-service';
+import { evaluateConditions } from './permission-evaluator';
+
+export interface PermissionExplanationSource {
+  /** Where the grant came from. */
+  via: 'direct-user' | 'direct-group' | 'direct-service-account' | 'role';
+  /** Role name when `via === 'role'`. */
+  role?: string;
+  /** Group id/name when the grant flows through a group (USER subjects only). */
+  group?: { id: string; name: string };
+  /** The matching permission row. */
+  permission: Permission;
+}
+
+export interface PermissionExplanation {
+  subject: Subject;
+  resource: string;
+  action: string;
+  /** Final verdict from the configured IAM evaluation mode and condition context. */
+  allowed: boolean;
+  /** Every grant source that matched, including DENYs. */
+  sources: PermissionExplanationSource[];
+  /** Roles the subject is bound to (whether or not their permissions matched). */
+  roleBindings: Array<{ role: string; tenantId?: string | null }>;
+  /** Groups the subject belongs to (USER only). */
+  groupMemberships: Array<{ id: string; name: string }>;
+}
+
+interface RoleBindingRow {
+  roleId: string;
+  tenantId: string | null;
+  subjectType: 'USER' | 'GROUP' | 'SERVICE_ACCOUNT';
+  subjectId: string;
+}
+
+interface DirectPermissionBindingRow {
+  permissionId: string;
+  tenantId: string | null;
+  subjectType: 'USER' | 'GROUP' | 'SERVICE_ACCOUNT';
+  subjectId: string;
+}
+
+interface GroupMembershipRow {
+  groupId: string;
+  userId: string;
+}
+
+interface GroupRow {
+  id: string;
+  name: string;
+}
+
+function permissionMatches(perm: Permission, resource: string, action: string): boolean {
+  const matchPart = (declared: string, actual: string): boolean => declared === actual || declared === '*';
+  return matchPart(perm.resource, resource) && matchPart(perm.action, action);
+}
+
+async function loadGroupMemberships(
+  db: DatabaseAdapter,
+  userId: string,
+): Promise<GroupRow[]> {
+  const memberships = await db.findMany<GroupMembershipRow>({
+    model: 'group_user',
+    where: [{ field: 'userId', operator: '=', value: userId }],
+  });
+  if (memberships.length === 0)
+    return [];
+  return db.findMany<GroupRow>({
+    model: 'group',
+    where: [{ field: 'id', operator: 'in', value: memberships.map(m => m.groupId) }],
+  });
+}
+
+async function loadRoleBindings(
+  db: DatabaseAdapter,
+  subject: { type: 'USER' | 'GROUP' | 'SERVICE_ACCOUNT'; id: string },
+): Promise<RoleBindingRow[]> {
+  return db.findMany<RoleBindingRow>({
+    model: 'role_binding',
+    where: [
+      { field: 'subjectType', operator: '=', value: subject.type },
+      { field: 'subjectId', operator: '=', value: subject.id },
+    ],
+  });
+}
+
+async function loadDirectBindings(
+  db: DatabaseAdapter,
+  subject: { type: 'USER' | 'GROUP' | 'SERVICE_ACCOUNT'; id: string },
+): Promise<DirectPermissionBindingRow[]> {
+  return db.findMany<DirectPermissionBindingRow>({
+    model: 'direct_permission_binding',
+    where: [
+      { field: 'subjectType', operator: '=', value: subject.type },
+      { field: 'subjectId', operator: '=', value: subject.id },
+    ],
+  });
+}
+
+async function loadPermissionsByIds(
+  db: DatabaseAdapter,
+  ids: string[],
+): Promise<Map<string, Permission>> {
+  if (ids.length === 0)
+    return new Map();
+  const rows = await db.findMany<Permission>({
+    model: 'permission',
+    where: [{ field: 'id', operator: 'in', value: ids }],
+  });
+  return new Map(rows.map(row => [row.id, row]));
+}
+
+async function loadRolePermissions(
+  db: DatabaseAdapter,
+  roleIds: string[],
+): Promise<Map<string, string[]>> {
+  if (roleIds.length === 0)
+    return new Map();
+  const links = await db.findMany<{ roleId: string; permissionId: string }>({
+    model: 'role_permission',
+    where: [{ field: 'roleId', operator: 'in', value: roleIds }],
+  });
+  const out = new Map<string, string[]>();
+  for (const link of links) {
+    const list = out.get(link.roleId) ?? [];
+    list.push(link.permissionId);
+    out.set(link.roleId, list);
+  }
+  return out;
+}
+
+async function loadRoles(db: DatabaseAdapter, ids: string[]): Promise<Map<string, Role>> {
+  if (ids.length === 0)
+    return new Map();
+  const rows = await db.findMany<Role>({
+    model: 'role',
+    where: [{ field: 'id', operator: 'in', value: ids }],
+  });
+  return new Map(rows.map(row => [row.id, row]));
+}
+
+/**
+ * Explain why a subject does (or does not) have a permission. Walks
+ * direct bindings, role bindings, and group memberships (USER only) and
+ * lists every matching grant with its source so operators can debug
+ * unexpected allow/deny results.
+ *
+ * @param db - Database adapter (typically `fortress.config.database`).
+ * @param iam - IAM service used for the authoritative verdict, including
+ *   configured evaluation mode, conditions, cache semantics, and inactive
+ *   service-account handling.
+ */
+export async function explainPermission(
+  db: DatabaseAdapter,
+  iam: IamService,
+  subject: Subject,
+  resource: string,
+  action: string,
+  context?: PermissionContext,
+): Promise<PermissionExplanation> {
+  const sources: PermissionExplanationSource[] = [];
+
+  // ── Group memberships (USER only) ──────────────────────────────────
+  const groupMemberships: GroupRow[] = subject.type === 'USER'
+    ? await loadGroupMemberships(db, subject.id)
+    : [];
+
+  // ── Role bindings: subject + inherited via groups ──────────────────
+  const directRoleBindings = await loadRoleBindings(db, subject);
+  const groupRoleBindings = await Promise.all(
+    groupMemberships.map(group => loadRoleBindings(db, { type: 'GROUP', id: group.id })),
+  );
+  // Map of roleId → { binding, viaGroup? }
+  const allRoleSources: Array<{ binding: RoleBindingRow; viaGroup?: GroupRow }> = [
+    ...directRoleBindings.map(binding => ({ binding })),
+    ...groupRoleBindings.flatMap((bindings, idx) =>
+      bindings.map(binding => ({ binding, viaGroup: groupMemberships[idx] })),
+    ),
+  ];
+  const roleIds = [...new Set(allRoleSources.map(s => s.binding.roleId))];
+  const rolesById = await loadRoles(db, roleIds);
+  const rolePermIds = await loadRolePermissions(db, roleIds);
+
+  // ── Direct permission bindings: subject + inherited via groups ─────
+  const directBindings = await loadDirectBindings(db, subject);
+  const groupDirectBindings = await Promise.all(
+    groupMemberships.map(group => loadDirectBindings(db, { type: 'GROUP', id: group.id })),
+  );
+  const allDirectSources: Array<{ binding: DirectPermissionBindingRow; viaGroup?: GroupRow }> = [
+    ...directBindings.map(binding => ({ binding })),
+    ...groupDirectBindings.flatMap((bindings, idx) =>
+      bindings.map(binding => ({ binding, viaGroup: groupMemberships[idx] })),
+    ),
+  ];
+
+  // ── Resolve every referenced permission row in one query ───────────
+  const permissionIds = new Set<string>();
+  for (const list of rolePermIds.values()) {
+    for (const id of list) permissionIds.add(id);
+  }
+  for (const source of allDirectSources) permissionIds.add(source.binding.permissionId);
+  const permsById = await loadPermissionsByIds(db, [...permissionIds]);
+
+  const tenantMatches = (tenantId: string | null): boolean => context?.tenantId
+    ? tenantId === null || tenantId === context.tenantId
+    : tenantId === null;
+  const conditionContext: PermissionContext = {
+    ...context,
+    user: {
+      ...context?.user,
+      id: subject.id,
+      subjectType: subject.type,
+      subjectId: subject.id,
+    },
+  };
+  const conditionsMatch = (permission: Permission): boolean => {
+    const raw = permission.conditions;
+    const conditions = typeof raw === 'string' ? JSON.parse(raw) as Permission['conditions'] : raw;
+    return !conditions?.length || evaluateConditions(conditions, conditionContext);
+  };
+  const subjectIsActive = subject.type !== 'SERVICE_ACCOUNT' || (await db.findOne<{ isActive: boolean }>({
+    model: 'service_account',
+    where: [{ field: 'id', operator: '=', value: subject.id }],
+  }))?.isActive === true;
+
+  // ── Direct grants ──────────────────────────────────────────────────
+  for (const { binding, viaGroup } of allDirectSources) {
+    const perm = permsById.get(binding.permissionId);
+    if (!subjectIsActive || !tenantMatches(binding.tenantId)
+      || !perm || !permissionMatches(perm, resource, action)
+      || !conditionsMatch(perm)) {
+      continue;
+    }
+    sources.push({
+      via: viaGroup
+        ? 'direct-group'
+        : subject.type === 'SERVICE_ACCOUNT'
+          ? 'direct-service-account'
+          : 'direct-user',
+      ...(viaGroup ? { group: { id: viaGroup.id, name: viaGroup.name } } : {}),
+      permission: perm,
+    });
+  }
+
+  // ── Role-based grants ──────────────────────────────────────────────
+  for (const { binding, viaGroup } of allRoleSources) {
+    const role = rolesById.get(binding.roleId);
+    if (!subjectIsActive || !tenantMatches(binding.tenantId) || !role)
+      continue;
+    const permIds = rolePermIds.get(binding.roleId) ?? [];
+    for (const permId of permIds) {
+      const perm = permsById.get(permId);
+      if (!perm || !permissionMatches(perm, resource, action)
+        || !conditionsMatch(perm)) {
+        continue;
+      }
+      sources.push({
+        via: 'role',
+        role: role.name,
+        ...(viaGroup ? { group: { id: viaGroup.id, name: viaGroup.name } } : {}),
+        permission: perm,
+      });
+    }
+  }
+
+  // Reuse the authoritative evaluator so explanation verdicts cannot drift
+  // from checkPermission's configured mode, conditions, or subject gates.
+  const allowed = await iam.checkPermission(subject, resource, action, context);
+
+  // Flatten role bindings for the result.
+  const roleBindings = allRoleSources
+    .filter(source => subjectIsActive && tenantMatches(source.binding.tenantId))
+    .map(s => ({ role: rolesById.get(s.binding.roleId)?.name ?? `role#${s.binding.roleId}`, tenantId: s.binding.tenantId }))
+    .filter((entry, idx, arr) => arr.findIndex(e => e.role === entry.role && e.tenantId === entry.tenantId) === idx);
+
+  return {
+    subject,
+    resource,
+    action,
+    allowed,
+    sources,
+    roleBindings,
+    groupMemberships: groupMemberships.map(group => ({ id: group.id, name: group.name })),
+  };
+}