@dwk/wac 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 David W. Keith
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# `@dwk/wac`
+
+Web Access Control (WAC) evaluation for Solid Pods. A pure, dependency-light
+library consumed by [`@dwk/solid-pod`](../solid-pod): it takes ACL graphs (as
+plain quads, compatible with [`@dwk/rdf`](../rdf) terms) plus request facts and
+returns an authorization decision. No Cloudflare bindings; unit-testable without
+a Workers runtime.
+
+See the [spec](../../spec/packages/wac.md) for the authoritative requirements,
+and the [Solid WAC specification](https://solidproject.org/TR/wac) for the model.
+
+## What it does
+
+- **Effective-ACL walk** — resolves the nearest applicable `.acl`, honoring
+  `acl:default` on ancestor containers. A resource's own `acl:accessTo` ACL
+  takes precedence over inherited `acl:default` ACLs.
+- **Modes** — `acl:Read`, `acl:Write`, `acl:Append`, `acl:Control`.
+- **Subjects** — `acl:agent`, `acl:agentGroup`, and `acl:agentClass`
+  (including `foaf:Agent` for public access and `acl:AuthenticatedAgent`).
+- **Origin** — `acl:origin` acts as a per-authorization allow-list.
+- **Append vs Write** — an `append` request is satisfied by `acl:Append` _or_
+  `acl:Write`; a delete must be requested as `write`, which `acl:Append` alone
+  never grants.
+
+> Decisions MUST NOT be memoized in eventually-consistent stores (e.g. KV); the
+> walk is cheap and is meant to run against strongly-consistent ACL state.
+
+## Usage
+
+```ts
+import { evaluateAccess, type AclResource } from "@dwk/wac";
+
+// Build the effective-ACL chain, nearest first. The requested resource's own
+// ACL uses scope "accessTo"; ancestor container ACLs use scope "default".
+const chain: AclResource[] = [
+  { target: "https://alice.example/notes/secret.ttl", scope: "accessTo", quads: resourceAclQuads },
+  { target: "https://alice.example/notes/", scope: "default", quads: containerAclQuads },
+];
+
+const decision = evaluateAccess(
+  { mode: "write", agent: "https://bob.example/card#me", origin: "https://app.example" },
+  chain,
+);
+
+if (!decision.granted) {
+  // 401 if unauthenticated, otherwise 403.
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * `@dwk/wac` — Web Access Control (WAC) evaluation for Solid Pods.
+ *
+ * @remarks
+ * Pure library: takes ACL graphs and request facts as plain data and returns an
+ * authorization decision. Tied to the Solid/WAC model by design, but carries no
+ * Cloudflare bindings and is unit-testable without a Workers runtime.
+ *
+ * The evaluator performs the effective-ACL walk (resolving the nearest
+ * applicable `.acl`, honoring `acl:default` on ancestor containers), evaluates
+ * `acl:Read`, `acl:Write`, `acl:Append`, and `acl:Control`, and supports
+ * `acl:agent`, `acl:agentGroup`, `acl:agentClass` (including `foaf:Agent` and
+ * `acl:AuthenticatedAgent`), and `acl:origin`.
+ *
+ * Callers MUST NOT memoize decisions in eventually-consistent stores; the walk
+ * is cheap and is meant to run against strongly-consistent ACL state.
+ *
+ * @see {@link https://solidproject.org/TR/wac | Solid WAC specification}
+ * @see spec/packages/wac.md
+ * @packageDocumentation
+ */
+import type { StoredTerm } from "@dwk/rdf";
+/**
+ * A plain RDF triple for ACL evaluation.
+ *
+ * @remarks
+ * Subject and predicate are always IRIs; the object may be an IRI (named node)
+ * shorthand string or a full {@link StoredTerm} from `@dwk/rdf`. WAC only
+ * matches named-node objects, so literals and blank nodes never match.
+ */
+export interface AclQuad {
+    /** Subject IRI. */
+    subject: string;
+    /** Predicate IRI. */
+    predicate: string;
+    /** Object: an IRI string, or a `@dwk/rdf` term. */
+    object: string | StoredTerm;
+}
+/**
+ * An access mode that may be requested or granted.
+ *
+ * @remarks
+ * `append` is implied by `write`: a request for `append` is satisfied by either
+ * an `acl:Append` or an `acl:Write` grant. A delete (which is not insert-only)
+ * MUST be requested as `write`, never `append`.
+ */
+export type AccessMode = "read" | "write" | "append" | "control";
+/** How an ACL document's authorizations attach to a resource. */
+export type AclScope = "accessTo" | "default";
+/**
+ * A single ACL document in the effective-ACL chain, as plain RDF quads.
+ *
+ * @remarks
+ * The chain is ordered nearest-first: the requested resource's own ACL (with
+ * {@link AclScope | scope} `"accessTo"`) comes first, followed by ancestor
+ * container ACLs (scope `"default"`) from closest to farthest. **Only ACL
+ * documents that exist (have a representation) are included.**
+ *
+ * Per WAC §5.1 the effective ACL is the *first* ancestor whose ACL resource
+ * exists, "regardless of whether it contains matching authorizations". Because
+ * every chain entry represents an existing ACL document, the **first entry is
+ * the effective ACL and is authoritative**: {@link evaluateAccess} decides from
+ * it alone — granted or denied — and never falls through (fail open) to a
+ * farther ancestor's `acl:default`. Selecting *which* ancestor's ACL exists is
+ * the caller's job; this library does not climb the hierarchy by inspecting
+ * authorization content. Entries after the first are not consulted, so callers
+ * SHOULD pass exactly the single effective ACL.
+ */
+export interface AclResource {
+    /**
+     * The IRI this ACL document governs: the requested resource for an
+     * `accessTo` entry, or the container for a `default` entry. Authorizations
+     * are matched against this IRI via the scope predicate.
+     */
+    target: string;
+    /** Which predicate links authorizations in this document to {@link target}. */
+    scope: AclScope;
+    /** The ACL document's statements, consumed from `@dwk/rdf`. */
+    quads: AclQuad[];
+}
+/** Facts about the agent and request being authorized. */
+export interface AccessRequest {
+    /** The requested access mode. */
+    mode: AccessMode;
+    /** The authenticated agent's WebID, if any. Absence means unauthenticated. */
+    agent?: string;
+    /** Group IRIs the agent is a member of, matched against `acl:agentGroup`. */
+    groups?: string[];
+    /** The request `Origin`, matched against `acl:origin` when present. */
+    origin?: string;
+}
+/** The outcome of an authorization evaluation. */
+export interface AccessDecision {
+    /** Whether the requested mode is granted. */
+    granted: boolean;
+    /**
+     * The modes granted to the agent by the effective ACL. Reports the modes
+     * literally asserted (`acl:Read`/`Write`/`Append`/`Control`); note that a
+     * `write` grant also satisfies an `append` request even when `append` is not
+     * listed here.
+     */
+    modes: AccessMode[];
+    /** The {@link AclResource.target} of the ACL that decided the request, if any. */
+    effectiveAcl?: string;
+}
+/**
+ * Evaluates a Web Access Control decision against an effective-ACL chain.
+ *
+ * @remarks
+ * Per WAC §5.1 the effective ACL is the *first* ancestor whose ACL resource
+ * exists, "regardless of whether it contains matching authorizations". The
+ * {@link AclResource | chain} lists existing ACL documents nearest-first, so its
+ * **first entry is the effective ACL and is authoritative**: the decision is
+ * made from that document alone — granted or denied — and never falls through
+ * (fail open) to a farther ancestor's `acl:default`, even when the document
+ * grants nothing for the target. This holds equally for a resource's own `.acl`
+ * (scope `"accessTo"`) and for an ancestor container's `acl:default`.
+ *
+ * Selecting *which* ancestor's ACL exists is the caller's responsibility (it is
+ * a function of resource existence, not authorization content); this library
+ * does not climb the hierarchy by inspecting authorizations, which would invert
+ * §5.1's stop condition. Entries after the first are not consulted.
+ *
+ * @param request - The agent and request facts to authorize.
+ * @param chain - The effective ACL as a one-element chain (nearest first).
+ * @returns The decision, including the granted modes and the effective ACL.
+ */
+export declare function evaluateAccess(request: AccessRequest, chain: AclResource[]): AccessDecision;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;CAC7B;AA4BD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjE,iEAAiE;AACjE,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,KAAK,EAAE,QAAQ,CAAC;IAChB,+DAA+D;IAC/D,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,IAAI,EAAE,UAAU,CAAC;IACjB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAgKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,WAAW,EAAE,GACnB,cAAc,CA0BhB"}

package/dist/index.js

@@ -0,0 +1,220 @@
+/**
+ * `@dwk/wac` — Web Access Control (WAC) evaluation for Solid Pods.
+ *
+ * @remarks
+ * Pure library: takes ACL graphs and request facts as plain data and returns an
+ * authorization decision. Tied to the Solid/WAC model by design, but carries no
+ * Cloudflare bindings and is unit-testable without a Workers runtime.
+ *
+ * The evaluator performs the effective-ACL walk (resolving the nearest
+ * applicable `.acl`, honoring `acl:default` on ancestor containers), evaluates
+ * `acl:Read`, `acl:Write`, `acl:Append`, and `acl:Control`, and supports
+ * `acl:agent`, `acl:agentGroup`, `acl:agentClass` (including `foaf:Agent` and
+ * `acl:AuthenticatedAgent`), and `acl:origin`.
+ *
+ * Callers MUST NOT memoize decisions in eventually-consistent stores; the walk
+ * is cheap and is meant to run against strongly-consistent ACL state.
+ *
+ * @see {@link https://solidproject.org/TR/wac | Solid WAC specification}
+ * @see spec/packages/wac.md
+ * @packageDocumentation
+ */
+/** WAC vocabulary base IRI. */
+const ACL = "http://www.w3.org/ns/auth/acl#";
+/** `rdf:type`. */
+const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+/** `foaf:Agent` — the class of all agents (public access). */
+const FOAF_AGENT = "http://xmlns.com/foaf/0.1/Agent";
+const ACL_AUTHORIZATION = `${ACL}Authorization`;
+const ACL_ACCESS_TO = `${ACL}accessTo`;
+const ACL_DEFAULT = `${ACL}default`;
+/** Legacy alias for `acl:default`, still seen in the wild. */
+const ACL_DEFAULT_FOR_NEW = `${ACL}defaultForNew`;
+const ACL_AGENT = `${ACL}agent`;
+const ACL_AGENT_GROUP = `${ACL}agentGroup`;
+const ACL_AGENT_CLASS = `${ACL}agentClass`;
+const ACL_MODE = `${ACL}mode`;
+const ACL_ORIGIN = `${ACL}origin`;
+const ACL_AUTHENTICATED_AGENT = `${ACL}AuthenticatedAgent`;
+const MODE_IRI = {
+    read: `${ACL}Read`,
+    write: `${ACL}Write`,
+    append: `${ACL}Append`,
+    control: `${ACL}Control`,
+};
+/**
+ * Returns the IRI of a quad object, or `undefined` if it is not a named node.
+ *
+ * Literals and blank nodes never match the named-node terms WAC cares about.
+ */
+function iri(object) {
+    if (typeof object === "string") {
+        return object;
+    }
+    return object?.termType === "NamedNode" ? object.value : undefined;
+}
+/** Collects the named-node object IRIs for all `(subject, predicate, *)` quads. */
+function collect(quads, subject, predicate) {
+    const values = [];
+    for (const q of quads) {
+        if (q.subject === subject && q.predicate === predicate) {
+            const value = iri(q.object);
+            if (value !== undefined) {
+                values.push(value);
+            }
+        }
+    }
+    return values;
+}
+/**
+ * Finds the authorizations in an ACL document that apply to its scoped target.
+ */
+function findApplicableAuthorizations(acl) {
+    if (!acl || !acl.quads) {
+        return [];
+    }
+    const { quads, scope, target } = acl;
+    const subjects = new Set();
+    for (const q of quads) {
+        if (q.predicate === RDF_TYPE && iri(q.object) === ACL_AUTHORIZATION) {
+            subjects.add(q.subject);
+        }
+    }
+    const authorizations = [];
+    for (const subject of subjects) {
+        const scoped = quads.some((q) => {
+            if (q.subject !== subject || iri(q.object) !== target) {
+                return false;
+            }
+            if (scope === "accessTo") {
+                return q.predicate === ACL_ACCESS_TO;
+            }
+            return q.predicate === ACL_DEFAULT || q.predicate === ACL_DEFAULT_FOR_NEW;
+        });
+        if (!scoped) {
+            continue;
+        }
+        authorizations.push({
+            subject,
+            modes: collect(quads, subject, ACL_MODE),
+            agents: collect(quads, subject, ACL_AGENT),
+            agentGroups: collect(quads, subject, ACL_AGENT_GROUP),
+            agentClasses: collect(quads, subject, ACL_AGENT_CLASS),
+            origins: collect(quads, subject, ACL_ORIGIN),
+        });
+    }
+    return authorizations;
+}
+/** Whether an authorization applies to the requesting agent. */
+function agentMatches(auth, request) {
+    // `foaf:Agent` is the public class — everyone, authenticated or not.
+    if (auth.agentClasses.includes(FOAF_AGENT)) {
+        return true;
+    }
+    // A non-empty WebID means authenticated; an empty string is not a valid
+    // identity and MUST NOT satisfy `acl:AuthenticatedAgent` or match a
+    // (malformed) empty `acl:agent`.
+    if (request.agent) {
+        if (auth.agentClasses.includes(ACL_AUTHENTICATED_AGENT)) {
+            return true;
+        }
+        if (auth.agents.includes(request.agent)) {
+            return true;
+        }
+    }
+    if (request.groups &&
+        auth.agentGroups.some((g) => request.groups.includes(g))) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Normalizes an origin to its `scheme://host[:port]` form so that comparisons
+ * ignore case and trailing-slash differences. Falls back to the raw value when
+ * it is not a parseable absolute URL, keeping the match fail-closed.
+ */
+function normalizeOrigin(value) {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Whether an authorization's origin restriction admits the request.
+ *
+ * An authorization with no `acl:origin` applies regardless of origin; one with
+ * origins acts as an allow-list. Both sides are normalized via {@link URL} so a
+ * correctly-configured allow-list is not defeated by case or a trailing slash.
+ */
+function originMatches(auth, request) {
+    if (auth.origins.length === 0) {
+        return true;
+    }
+    if (request.origin === undefined) {
+        return false;
+    }
+    const requestOrigin = normalizeOrigin(request.origin);
+    return auth.origins.some((o) => normalizeOrigin(o) === requestOrigin);
+}
+/** Whether the granted mode IRIs satisfy the requested mode. */
+function isModeSatisfied(required, granted) {
+    if (required === "append") {
+        // Append authorizes insert-only patches and is implied by Write.
+        return granted.has(MODE_IRI.append) || granted.has(MODE_IRI.write);
+    }
+    return granted.has(MODE_IRI[required]);
+}
+/** Maps the granted mode IRIs back to {@link AccessMode} values. */
+function toAccessModes(granted) {
+    return Object.keys(MODE_IRI).filter((mode) => granted.has(MODE_IRI[mode]));
+}
+/**
+ * Evaluates a Web Access Control decision against an effective-ACL chain.
+ *
+ * @remarks
+ * Per WAC §5.1 the effective ACL is the *first* ancestor whose ACL resource
+ * exists, "regardless of whether it contains matching authorizations". The
+ * {@link AclResource | chain} lists existing ACL documents nearest-first, so its
+ * **first entry is the effective ACL and is authoritative**: the decision is
+ * made from that document alone — granted or denied — and never falls through
+ * (fail open) to a farther ancestor's `acl:default`, even when the document
+ * grants nothing for the target. This holds equally for a resource's own `.acl`
+ * (scope `"accessTo"`) and for an ancestor container's `acl:default`.
+ *
+ * Selecting *which* ancestor's ACL exists is the caller's responsibility (it is
+ * a function of resource existence, not authorization content); this library
+ * does not climb the hierarchy by inspecting authorizations, which would invert
+ * §5.1's stop condition. Entries after the first are not consulted.
+ *
+ * @param request - The agent and request facts to authorize.
+ * @param chain - The effective ACL as a one-element chain (nearest first).
+ * @returns The decision, including the granted modes and the effective ACL.
+ */
+export function evaluateAccess(request, chain) {
+    if (!request || !chain || !Array.isArray(chain)) {
+        return { granted: false, modes: [] };
+    }
+    // The first chain entry is an existing ACL document, hence the effective ACL
+    // per §5.1; it is authoritative whether or not it carries a matching
+    // authorization, so the decision is taken from it alone (fail closed).
+    const acl = chain[0];
+    if (!acl) {
+        return { granted: false, modes: [] };
+    }
+    const granted = new Set();
+    for (const auth of findApplicableAuthorizations(acl)) {
+        if (agentMatches(auth, request) && originMatches(auth, request)) {
+            for (const mode of auth.modes) {
+                granted.add(mode);
+            }
+        }
+    }
+    return {
+        granted: isModeSatisfied(request.mode, granted),
+        modes: toAccessModes(granted),
+        effectiveAcl: acl.target,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@dwk/wac",
+  "version": "0.1.0-beta.0",
+  "description": "Web Access Control evaluation (effective-ACL walk, Append vs Write). Solid-specific helper.",
+  "keywords": [
+    "web-access-control",
+    "wac",
+    "solid",
+    "authorization",
+    "acl",
+    "linked-data"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/wac#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/wac"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dwk/rdf": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/index.ts

@@ -0,0 +1,349 @@
+/**
+ * `@dwk/wac` — Web Access Control (WAC) evaluation for Solid Pods.
+ *
+ * @remarks
+ * Pure library: takes ACL graphs and request facts as plain data and returns an
+ * authorization decision. Tied to the Solid/WAC model by design, but carries no
+ * Cloudflare bindings and is unit-testable without a Workers runtime.
+ *
+ * The evaluator performs the effective-ACL walk (resolving the nearest
+ * applicable `.acl`, honoring `acl:default` on ancestor containers), evaluates
+ * `acl:Read`, `acl:Write`, `acl:Append`, and `acl:Control`, and supports
+ * `acl:agent`, `acl:agentGroup`, `acl:agentClass` (including `foaf:Agent` and
+ * `acl:AuthenticatedAgent`), and `acl:origin`.
+ *
+ * Callers MUST NOT memoize decisions in eventually-consistent stores; the walk
+ * is cheap and is meant to run against strongly-consistent ACL state.
+ *
+ * @see {@link https://solidproject.org/TR/wac | Solid WAC specification}
+ * @see spec/packages/wac.md
+ * @packageDocumentation
+ */
+
+import type { StoredTerm } from "@dwk/rdf";
+
+/**
+ * A plain RDF triple for ACL evaluation.
+ *
+ * @remarks
+ * Subject and predicate are always IRIs; the object may be an IRI (named node)
+ * shorthand string or a full {@link StoredTerm} from `@dwk/rdf`. WAC only
+ * matches named-node objects, so literals and blank nodes never match.
+ */
+export interface AclQuad {
+  /** Subject IRI. */
+  subject: string;
+  /** Predicate IRI. */
+  predicate: string;
+  /** Object: an IRI string, or a `@dwk/rdf` term. */
+  object: string | StoredTerm;
+}
+
+/** WAC vocabulary base IRI. */
+const ACL = "http://www.w3.org/ns/auth/acl#";
+/** `rdf:type`. */
+const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
+/** `foaf:Agent` — the class of all agents (public access). */
+const FOAF_AGENT = "http://xmlns.com/foaf/0.1/Agent";
+
+const ACL_AUTHORIZATION = `${ACL}Authorization`;
+const ACL_ACCESS_TO = `${ACL}accessTo`;
+const ACL_DEFAULT = `${ACL}default`;
+/** Legacy alias for `acl:default`, still seen in the wild. */
+const ACL_DEFAULT_FOR_NEW = `${ACL}defaultForNew`;
+const ACL_AGENT = `${ACL}agent`;
+const ACL_AGENT_GROUP = `${ACL}agentGroup`;
+const ACL_AGENT_CLASS = `${ACL}agentClass`;
+const ACL_MODE = `${ACL}mode`;
+const ACL_ORIGIN = `${ACL}origin`;
+const ACL_AUTHENTICATED_AGENT = `${ACL}AuthenticatedAgent`;
+
+const MODE_IRI: Record<AccessMode, string> = {
+  read: `${ACL}Read`,
+  write: `${ACL}Write`,
+  append: `${ACL}Append`,
+  control: `${ACL}Control`,
+};
+
+/**
+ * An access mode that may be requested or granted.
+ *
+ * @remarks
+ * `append` is implied by `write`: a request for `append` is satisfied by either
+ * an `acl:Append` or an `acl:Write` grant. A delete (which is not insert-only)
+ * MUST be requested as `write`, never `append`.
+ */
+export type AccessMode = "read" | "write" | "append" | "control";
+
+/** How an ACL document's authorizations attach to a resource. */
+export type AclScope = "accessTo" | "default";
+
+/**
+ * A single ACL document in the effective-ACL chain, as plain RDF quads.
+ *
+ * @remarks
+ * The chain is ordered nearest-first: the requested resource's own ACL (with
+ * {@link AclScope | scope} `"accessTo"`) comes first, followed by ancestor
+ * container ACLs (scope `"default"`) from closest to farthest. **Only ACL
+ * documents that exist (have a representation) are included.**
+ *
+ * Per WAC §5.1 the effective ACL is the *first* ancestor whose ACL resource
+ * exists, "regardless of whether it contains matching authorizations". Because
+ * every chain entry represents an existing ACL document, the **first entry is
+ * the effective ACL and is authoritative**: {@link evaluateAccess} decides from
+ * it alone — granted or denied — and never falls through (fail open) to a
+ * farther ancestor's `acl:default`. Selecting *which* ancestor's ACL exists is
+ * the caller's job; this library does not climb the hierarchy by inspecting
+ * authorization content. Entries after the first are not consulted, so callers
+ * SHOULD pass exactly the single effective ACL.
+ */
+export interface AclResource {
+  /**
+   * The IRI this ACL document governs: the requested resource for an
+   * `accessTo` entry, or the container for a `default` entry. Authorizations
+   * are matched against this IRI via the scope predicate.
+   */
+  target: string;
+  /** Which predicate links authorizations in this document to {@link target}. */
+  scope: AclScope;
+  /** The ACL document's statements, consumed from `@dwk/rdf`. */
+  quads: AclQuad[];
+}
+
+/** Facts about the agent and request being authorized. */
+export interface AccessRequest {
+  /** The requested access mode. */
+  mode: AccessMode;
+  /** The authenticated agent's WebID, if any. Absence means unauthenticated. */
+  agent?: string;
+  /** Group IRIs the agent is a member of, matched against `acl:agentGroup`. */
+  groups?: string[];
+  /** The request `Origin`, matched against `acl:origin` when present. */
+  origin?: string;
+}
+
+/** The outcome of an authorization evaluation. */
+export interface AccessDecision {
+  /** Whether the requested mode is granted. */
+  granted: boolean;
+  /**
+   * The modes granted to the agent by the effective ACL. Reports the modes
+   * literally asserted (`acl:Read`/`Write`/`Append`/`Control`); note that a
+   * `write` grant also satisfies an `append` request even when `append` is not
+   * listed here.
+   */
+  modes: AccessMode[];
+  /** The {@link AclResource.target} of the ACL that decided the request, if any. */
+  effectiveAcl?: string;
+}
+
+/** A normalized authorization extracted from an ACL document. */
+interface Authorization {
+  subject: string;
+  modes: string[];
+  agents: string[];
+  agentGroups: string[];
+  agentClasses: string[];
+  origins: string[];
+}
+
+/**
+ * Returns the IRI of a quad object, or `undefined` if it is not a named node.
+ *
+ * Literals and blank nodes never match the named-node terms WAC cares about.
+ */
+function iri(object: AclQuad["object"]): string | undefined {
+  if (typeof object === "string") {
+    return object;
+  }
+  return object?.termType === "NamedNode" ? object.value : undefined;
+}
+
+/** Collects the named-node object IRIs for all `(subject, predicate, *)` quads. */
+function collect(
+  quads: AclQuad[],
+  subject: string,
+  predicate: string,
+): string[] {
+  const values: string[] = [];
+  for (const q of quads) {
+    if (q.subject === subject && q.predicate === predicate) {
+      const value = iri(q.object);
+      if (value !== undefined) {
+        values.push(value);
+      }
+    }
+  }
+  return values;
+}
+
+/**
+ * Finds the authorizations in an ACL document that apply to its scoped target.
+ */
+function findApplicableAuthorizations(acl: AclResource): Authorization[] {
+  if (!acl || !acl.quads) {
+    return [];
+  }
+  const { quads, scope, target } = acl;
+
+  const subjects = new Set<string>();
+  for (const q of quads) {
+    if (q.predicate === RDF_TYPE && iri(q.object) === ACL_AUTHORIZATION) {
+      subjects.add(q.subject);
+    }
+  }
+
+  const authorizations: Authorization[] = [];
+  for (const subject of subjects) {
+    const scoped = quads.some((q) => {
+      if (q.subject !== subject || iri(q.object) !== target) {
+        return false;
+      }
+      if (scope === "accessTo") {
+        return q.predicate === ACL_ACCESS_TO;
+      }
+      return q.predicate === ACL_DEFAULT || q.predicate === ACL_DEFAULT_FOR_NEW;
+    });
+    if (!scoped) {
+      continue;
+    }
+    authorizations.push({
+      subject,
+      modes: collect(quads, subject, ACL_MODE),
+      agents: collect(quads, subject, ACL_AGENT),
+      agentGroups: collect(quads, subject, ACL_AGENT_GROUP),
+      agentClasses: collect(quads, subject, ACL_AGENT_CLASS),
+      origins: collect(quads, subject, ACL_ORIGIN),
+    });
+  }
+  return authorizations;
+}
+
+/** Whether an authorization applies to the requesting agent. */
+function agentMatches(auth: Authorization, request: AccessRequest): boolean {
+  // `foaf:Agent` is the public class — everyone, authenticated or not.
+  if (auth.agentClasses.includes(FOAF_AGENT)) {
+    return true;
+  }
+  // A non-empty WebID means authenticated; an empty string is not a valid
+  // identity and MUST NOT satisfy `acl:AuthenticatedAgent` or match a
+  // (malformed) empty `acl:agent`.
+  if (request.agent) {
+    if (auth.agentClasses.includes(ACL_AUTHENTICATED_AGENT)) {
+      return true;
+    }
+    if (auth.agents.includes(request.agent)) {
+      return true;
+    }
+  }
+  if (
+    request.groups &&
+    auth.agentGroups.some((g) => request.groups!.includes(g))
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Normalizes an origin to its `scheme://host[:port]` form so that comparisons
+ * ignore case and trailing-slash differences. Falls back to the raw value when
+ * it is not a parseable absolute URL, keeping the match fail-closed.
+ */
+function normalizeOrigin(value: string): string {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Whether an authorization's origin restriction admits the request.
+ *
+ * An authorization with no `acl:origin` applies regardless of origin; one with
+ * origins acts as an allow-list. Both sides are normalized via {@link URL} so a
+ * correctly-configured allow-list is not defeated by case or a trailing slash.
+ */
+function originMatches(auth: Authorization, request: AccessRequest): boolean {
+  if (auth.origins.length === 0) {
+    return true;
+  }
+  if (request.origin === undefined) {
+    return false;
+  }
+  const requestOrigin = normalizeOrigin(request.origin);
+  return auth.origins.some((o) => normalizeOrigin(o) === requestOrigin);
+}
+
+/** Whether the granted mode IRIs satisfy the requested mode. */
+function isModeSatisfied(
+  required: AccessMode,
+  granted: ReadonlySet<string>,
+): boolean {
+  if (required === "append") {
+    // Append authorizes insert-only patches and is implied by Write.
+    return granted.has(MODE_IRI.append) || granted.has(MODE_IRI.write);
+  }
+  return granted.has(MODE_IRI[required]);
+}
+
+/** Maps the granted mode IRIs back to {@link AccessMode} values. */
+function toAccessModes(granted: ReadonlySet<string>): AccessMode[] {
+  return (Object.keys(MODE_IRI) as AccessMode[]).filter((mode) =>
+    granted.has(MODE_IRI[mode]),
+  );
+}
+
+/**
+ * Evaluates a Web Access Control decision against an effective-ACL chain.
+ *
+ * @remarks
+ * Per WAC §5.1 the effective ACL is the *first* ancestor whose ACL resource
+ * exists, "regardless of whether it contains matching authorizations". The
+ * {@link AclResource | chain} lists existing ACL documents nearest-first, so its
+ * **first entry is the effective ACL and is authoritative**: the decision is
+ * made from that document alone — granted or denied — and never falls through
+ * (fail open) to a farther ancestor's `acl:default`, even when the document
+ * grants nothing for the target. This holds equally for a resource's own `.acl`
+ * (scope `"accessTo"`) and for an ancestor container's `acl:default`.
+ *
+ * Selecting *which* ancestor's ACL exists is the caller's responsibility (it is
+ * a function of resource existence, not authorization content); this library
+ * does not climb the hierarchy by inspecting authorizations, which would invert
+ * §5.1's stop condition. Entries after the first are not consulted.
+ *
+ * @param request - The agent and request facts to authorize.
+ * @param chain - The effective ACL as a one-element chain (nearest first).
+ * @returns The decision, including the granted modes and the effective ACL.
+ */
+export function evaluateAccess(
+  request: AccessRequest,
+  chain: AclResource[],
+): AccessDecision {
+  if (!request || !chain || !Array.isArray(chain)) {
+    return { granted: false, modes: [] };
+  }
+  // The first chain entry is an existing ACL document, hence the effective ACL
+  // per §5.1; it is authoritative whether or not it carries a matching
+  // authorization, so the decision is taken from it alone (fail closed).
+  const acl = chain[0];
+  if (!acl) {
+    return { granted: false, modes: [] };
+  }
+
+  const granted = new Set<string>();
+  for (const auth of findApplicableAuthorizations(acl)) {
+    if (agentMatches(auth, request) && originMatches(auth, request)) {
+      for (const mode of auth.modes) {
+        granted.add(mode);
+      }
+    }
+  }
+
+  return {
+    granted: isModeSatisfied(request.mode, granted),
+    modes: toAccessModes(granted),
+    effectiveAcl: acl.target,
+  };
+}