Add Phase III OAuth ACL enforcement for DFS endpoint

Implement OAuth with ACL enforcement as specified by the Azurite ADLS Gen2
wiki Phase III ("OAuth: ACL works when user login with AAD account").

- OAuthLevel: Add ACL level (--oauth acl) alongside existing BASIC level.
- ConfigurationBase: Accept "acl" as --oauth parameter value.
- DfsContext: Add IDfsAuthenticatedIdentity interface with oid, upn, tid,
  appid fields; add identity field to IDfsContext.
- DfsAuthenticationMiddleware: Extract identity claims (oid, upn, tid,
  appid) from Bearer JWT tokens when ACL mode is active; store in DFS
  context for downstream enforcement.
- DfsAclEnforcer: New module implementing POSIX ACL evaluation:
  - Parses ACL strings ("user::rwx,user:oid:r-x,group::r-x,other::---")
  - Evaluates in POSIX order: owner -> named user -> group -> other
  - Applies mask entries to limit named user/group permissions
  - $superuser and unauthenticated requests bypass checks
  - Maps operations to required permissions (r/w/x)
- PathHandler: Add enforceAcl() helper; check ACL before getProperties,
  read, delete, and update operations; accept OAuthLevel from factory.
- DfsRequestListenerFactory: Pass OAuth level to PathHandler.
- Tests: 19 unit tests for ACL enforcer covering parsing, bypass scenarios,
  owner/named-user/group/other permissions, mask application, and UPN
  matching. All passing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Skrypt

src/blob/DfsRequestListenerFactory.ts

@@ -57,7 +57,7 @@ export default class DfsRequestListenerFactory implements IRequestListenerFactor
     const app = express().disable("x-powered-by");
 
     const filesystemHandler = new FilesystemHandler(this.metadataStore, this.enableHierarchicalNamespace);
-    const pathHandler = new PathHandler(this.metadataStore, this.extentStore);
+    const pathHandler = new PathHandler(this.metadataStore, this.extentStore, this.oauth);
 
     // Parse raw body for append operations
     app.use(express.raw({ type: "*/*", limit: "256mb" }));

src/blob/dfs/DfsAclEnforcer.ts

@@ -0,0 +1,213 @@
+/**
+ * ACL Enforcement for DFS (ADLS Gen2) operations.
+ *
+ * Phase III: When --oauth acl is enabled, checks the caller's identity
+ * against POSIX ACL entries stored on each path before allowing operations.
+ *
+ * ACL format follows Azure ADLS Gen2:
+ *   "user::rwx,user:oid:r-x,group::r-x,other::---"
+ *
+ * Limitations (per wiki guidance):
+ *   - No AAD group membership resolution
+ *   - $superuser identity bypasses all ACL checks
+ *   - Emulator mode (no identity) bypasses all checks
+ */
+
+import { IDfsAuthenticatedIdentity } from "./DfsContext";
+
+/** Required permission for an operation */
+export type AclPermission = "r" | "w" | "x";
+
+/**
+ * Maps DFS operations to the minimum required permission.
+ */
+export function getRequiredPermission(
+  operationDescription: string
+): AclPermission {
+  switch (operationDescription) {
+    case "read":
+    case "getProperties":
+    case "getAccessControl":
+    case "listPaths":
+      return "r";
+    case "create":
+    case "delete":
+    case "update":
+    case "setAccessControl":
+    case "setProperties":
+    case "rename":
+    case "lease":
+      return "w";
+    case "listChildren":
+      return "x";
+    default:
+      return "r";
+  }
+}
+
+/**
+ * Parsed ACL entry.
+ * Format: "type:entityId:permissions"
+ * Examples: "user::rwx", "user:abc-123:r-x", "group::r--", "other::---"
+ */
+export interface AclEntry {
+  type: "user" | "group" | "mask" | "other";
+  entityId: string; // empty string for default user/group/other
+  read: boolean;
+  write: boolean;
+  execute: boolean;
+}
+
+/**
+ * Parse an ACL string into structured entries.
+ * ACL format: "user::rwx,user:abc:r-x,group::r-x,mask::rwx,other::---"
+ */
+export function parseAcl(aclString: string | undefined): AclEntry[] {
+  if (!aclString) return [];
+
+  return aclString.split(",").filter(Boolean).map(entry => {
+    const parts = entry.split(":");
+    if (parts.length < 3) return null;
+
+    const type = parts[0] as AclEntry["type"];
+    const entityId = parts[1];
+    const perms = parts[2];
+
+    return {
+      type,
+      entityId,
+      read: perms.charAt(0) === "r",
+      write: perms.charAt(1) === "w",
+      execute: perms.charAt(2) === "x"
+    };
+  }).filter((e): e is AclEntry => e !== null);
+}
+
+/**
+ * Check if an ACL entry grants the required permission.
+ */
+function entryHasPermission(entry: AclEntry, permission: AclPermission): boolean {
+  switch (permission) {
+    case "r": return entry.read;
+    case "w": return entry.write;
+    case "x": return entry.execute;
+  }
+}
+
+/**
+ * Result of an ACL check.
+ */
+export interface AclCheckResult {
+  allowed: boolean;
+  reason: string;
+}
+
+/**
+ * Check whether the given identity is authorized for the required permission
+ * based on the path's ACL metadata.
+ *
+ * Algorithm follows the POSIX ACL evaluation order:
+ *   1. If owner matches identity → use owner permissions
+ *   2. If a named user entry matches identity → use that entry (masked)
+ *   3. If group matches → use group permissions (masked)
+ *   4. Fall through to other permissions
+ *
+ * Special cases:
+ *   - $superuser always passes (emulator admin)
+ *   - No identity (unauthenticated) always passes (emulator dev mode)
+ *   - No ACL metadata → use default permissions (rwxr-x---)
+ */
+export function checkAcl(
+  identity: IDfsAuthenticatedIdentity | undefined,
+  owner: string | undefined,
+  group: string | undefined,
+  permissionsStr: string | undefined,
+  aclStr: string | undefined,
+  requiredPermission: AclPermission
+): AclCheckResult {
+  // No identity = emulator/dev mode → bypass
+  if (!identity || (!identity.oid && !identity.upn)) {
+    return { allowed: true, reason: "No authenticated identity — emulator mode bypass" };
+  }
+
+  // $superuser bypasses all ACL checks
+  const effectiveOwner = owner || "$superuser";
+  if (effectiveOwner === "$superuser") {
+    return { allowed: true, reason: "$superuser bypasses ACL checks" };
+  }
+
+  const callerId = identity.oid || identity.upn || "";
+
+  // Check if caller is the owner
+  if (callerId === effectiveOwner) {
+    // Use owner permissions from the permissions string (chars 0-2)
+    const perms = permissionsStr || "rwxr-x---";
+    const ownerPerms: AclEntry = {
+      type: "user",
+      entityId: "",
+      read: perms.charAt(0) === "r",
+      write: perms.charAt(1) === "w",
+      execute: perms.charAt(2) === "x"
+    };
+    if (entryHasPermission(ownerPerms, requiredPermission)) {
+      return { allowed: true, reason: "Owner permission granted" };
+    }
+    return { allowed: false, reason: "Owner does not have required permission" };
+  }
+
+  // Parse ACL entries for named user/group matching
+  const aclEntries = parseAcl(aclStr);
+
+  // Find mask entry (used to limit named user and group permissions)
+  const maskEntry = aclEntries.find(e => e.type === "mask" && e.entityId === "");
+
+  // Check named user entries
+  const namedUser = aclEntries.find(
+    e => e.type === "user" && e.entityId !== "" && e.entityId === callerId
+  );
+  if (namedUser) {
+    const effective = maskEntry
+      ? entryHasPermission(namedUser, requiredPermission) && entryHasPermission(maskEntry, requiredPermission)
+      : entryHasPermission(namedUser, requiredPermission);
+    if (effective) {
+      return { allowed: true, reason: `Named user ACL entry matched (${callerId})` };
+    }
+    return { allowed: false, reason: `Named user ACL entry matched but lacks permission` };
+  }
+
+  // Check group (we can't resolve AD group membership per wiki constraints,
+  // so we only check the owning group if the caller matches it)
+  const effectiveGroup = group || "$superuser";
+  if (callerId === effectiveGroup) {
+    const perms = permissionsStr || "rwxr-x---";
+    const groupPerms: AclEntry = {
+      type: "group",
+      entityId: "",
+      read: perms.charAt(3) === "r",
+      write: perms.charAt(4) === "w",
+      execute: perms.charAt(5) === "x"
+    };
+    const effective = maskEntry
+      ? entryHasPermission(groupPerms, requiredPermission) && entryHasPermission(maskEntry, requiredPermission)
+      : entryHasPermission(groupPerms, requiredPermission);
+    if (effective) {
+      return { allowed: true, reason: "Group permission granted" };
+    }
+    return { allowed: false, reason: "Group does not have required permission" };
+  }
+
+  // Fall through to "other" permissions (chars 6-8)
+  const perms = permissionsStr || "rwxr-x---";
+  const otherPerms: AclEntry = {
+    type: "other",
+    entityId: "",
+    read: perms.charAt(6) === "r",
+    write: perms.charAt(7) === "w",
+    execute: perms.charAt(8) === "x"
+  };
+  if (entryHasPermission(otherPerms, requiredPermission)) {
+    return { allowed: true, reason: "Other permission granted" };
+  }
+
+  return { allowed: false, reason: "Insufficient ACL permissions" };
+}

src/blob/dfs/DfsAuthenticationMiddleware.ts

@@ -1,3 +1,4 @@
+import { decode } from "jsonwebtoken";
 import { NextFunction, Request, RequestHandler, Response } from "express";
 
 import IAccountDataStore from "../../common/IAccountDataStore";
@@ -12,10 +13,11 @@ import ExpressRequestAdapter from "../generated/ExpressRequestAdapter";
 
 import Operation from "../generated/artifacts/operation";
 import IBlobMetadataStore from "../persistence/IBlobMetadataStore";
-import { getDfsContext } from "./DfsContext";
+import { getDfsContext, IDfsAuthenticatedIdentity } from "./DfsContext";
 import { DfsOperation } from "./DfsOperation";
 import { sendDfsError } from "./DfsErrorFactory";
 import { OAuthLevel } from "../../common/models";
+import { BEARER_TOKEN_PREFIX } from "../../common/utils/constants";
 
 const DEFAULT_CONTEXT_PATH = "dfs_blob_context";
 
@@ -55,6 +57,32 @@ function mapDfsOperationToBlobOperation(op?: DfsOperation): Operation {
   }
 }
 
+/**
+ * Extracts identity claims from a Bearer JWT token.
+ * Returns undefined if the token is not a Bearer token or can't be decoded.
+ */
+function extractIdentityFromRequest(req: Request): IDfsAuthenticatedIdentity | undefined {
+  const authHeader = req.header("authorization");
+  if (!authHeader || !authHeader.startsWith(BEARER_TOKEN_PREFIX)) {
+    return undefined;
+  }
+
+  const token = authHeader.substring(BEARER_TOKEN_PREFIX.length + 1);
+  try {
+    const decoded = decode(token) as { [key: string]: any } | null;
+    if (!decoded) return undefined;
+
+    return {
+      oid: decoded.oid as string | undefined,
+      upn: decoded.upn as string | undefined,
+      tid: decoded.tid as string | undefined,
+      appid: decoded.appid as string | undefined
+    };
+  } catch {
+    return undefined;
+  }
+}
+
 export default function createDfsAuthenticationMiddleware(
   accountDataStore: IAccountDataStore,
   metadataStore: IBlobMetadataStore,
@@ -118,6 +146,12 @@ export default function createDfsAuthenticationMiddleware(
         return;
       }
 
+      // When ACL mode is enabled, extract identity from bearer token
+      // so ACL enforcement can check permissions downstream
+      if (oauth === OAuthLevel.ACL) {
+        dfsCtx.identity = extractIdentityFromRequest(req);
+      }
+
       next();
     } catch (error: any) {
       if (error.statusCode) {

src/blob/dfs/DfsContext.ts

@@ -7,6 +7,21 @@ import { SECONDARY_SUFFIX, HeaderConstants, ValidAPIVersions, VERSION } from "..
 import { checkApiVersion } from "../utils/utils";
 import { DfsOperation } from "./DfsOperation";
 
+/**
+ * Identity extracted from an OAuth bearer token.
+ * Used for ACL enforcement in Phase III (--oauth acl).
+ */
+export interface IDfsAuthenticatedIdentity {
+  /** Azure AD object ID (oid claim) */
+  oid?: string;
+  /** User principal name (upn claim) */
+  upn?: string;
+  /** Tenant ID (tid claim) */
+  tid?: string;
+  /** Application ID (appid claim) */
+  appid?: string;
+}
+
 export interface IDfsContext {
   requestId: string;
   startTime: Date;
@@ -16,6 +31,8 @@ export interface IDfsContext {
   isSecondary?: boolean;
   operation?: DfsOperation;
   authenticationPath?: string;
+  /** Authenticated identity from OAuth token — populated when --oauth acl is enabled */
+  identity?: IDfsAuthenticatedIdentity;
 }
 
 const DFS_CONTEXT_KEY = "dfsContext";