feat: emit relative acl:agent in pod creation

melvincarvalho · melvincarvalho · commit fa368e382e29 · 2026-05-14T06:09:53.000+02:00
Phase 2 of JavaScriptSolidServer#427 (JavaScriptSolidServer#430). Builds on JavaScriptSolidServer#429 (relative accessTo/default). The owner WebID lives at <pod>/profile/card.jsonld#me. Each .acl now references it relative to that .acl's container — './profile/card.jsonld#me' from the pod root, '../profile/card.jsonld#me' from an immediate child folder, './card.jsonld#me' from /profile/.acl. The parser already resolves relative agent URIs against the .acl URL (PR JavaScriptSolidServer#65 / JavaScriptSolidServer#64), so this is a writer-side change only. Existing absolute-agent ACLs on disk continue to authorize correctly. Together with JavaScriptSolidServer#429 the on-disk pod is now host-portable: an operator can `mv` a pod directory to a different domain without rewriting any ACL files. Same-host owner read/write keeps working — covered by existing pod creation / ACL access tests. The `webId` parameter on createPodStructure / createRootPodStructure remains the absolute WebID URI: it is still the global identifier published in the profile document and consumed by OIDC, federation, typeIndex generation, etc. Only the in-ACL references become relative. Cross-host *owner write* (token issued by host A, request to host B) still mismatches because the token's `webid` claim is fixed at auth time; that's Phase 4 and needs its own design. Tests: - 4 unit tests (one per affected generator) verify a relative agent string is preserved verbatim. - 2 round-trip tests parse the same on-wire ACL under different host URLs and assert the agent resolves to the requesting host, including the parent-relative '../profile/card.jsonld#me' from a child folder. 793/793 tests pass.
diff --git a/src/handlers/container.js b/src/handlers/container.js
@@ -195,31 +195,42 @@ export async function createPodStructure(name, webId, podUri, issuer, defaultQuo
 
   // Create default ACL files. Each .acl is written inside the container it
   // protects, so the resource it refers to is always './' (resolved against
-  // the .acl's own URL by the parser — see #428). This keeps pods portable
-  // across hostnames; the absolute podUri is no longer baked in.
-  const rootAcl = generateOwnerAcl('./', webId, true);
+  // the .acl's own URL by the parser — see #428).
+  //
+  // The owner WebID is also written relatively (#430). The WebID lives at
+  // <pod>/profile/card.jsonld#me, so each .acl references it relative to
+  // that .acl's container — './profile/card.jsonld#me' from the root,
+  // '../profile/card.jsonld#me' from an immediate child folder, etc.
+  // This keeps the on-disk pod portable across hostnames; the absolute
+  // podUri is no longer baked into either accessTo or agent.
+  const ownerFromRoot = './profile/card.jsonld#me';
+  const ownerFromChild = '../profile/card.jsonld#me';
+  const ownerFromProfile = './card.jsonld#me';
+
+  const rootAcl = generateOwnerAcl('./', ownerFromRoot, true);
   await storage.write(`${podPath}.acl`, serializeAcl(rootAcl));
 
-  const privateAcl = generatePrivateAcl('./', webId);
+  const privateAcl = generatePrivateAcl('./', ownerFromChild);
   await storage.write(`${podPath}private/.acl`, serializeAcl(privateAcl));
 
-  const settingsAcl = generatePrivateAcl('./', webId);
+  const settingsAcl = generatePrivateAcl('./', ownerFromChild);
   await storage.write(`${podPath}settings/.acl`, serializeAcl(settingsAcl));
 
   // publicTypeIndex: public read, overrides the private default inherited
   // from /settings/. This is a resource ACL (lives at .../publicTypeIndex.jsonld.acl),
   // so the resource is './publicTypeIndex.jsonld' relative to the parent.
-  const publicTypeIndexAcl = generateOwnerAcl('./publicTypeIndex.jsonld', webId, false);
+  // The .acl's base URL is /settings/, so the agent is one level up.
+  const publicTypeIndexAcl = generateOwnerAcl('./publicTypeIndex.jsonld', ownerFromChild, false);
   await storage.write(`${podPath}settings/publicTypeIndex.jsonld.acl`, serializeAcl(publicTypeIndexAcl));
 
-  const inboxAcl = generateInboxAcl('./', webId);
+  const inboxAcl = generateInboxAcl('./', ownerFromChild);
   await storage.write(`${podPath}inbox/.acl`, serializeAcl(inboxAcl));
 
-  const publicAcl = generatePublicFolderAcl('./', webId);
+  const publicAcl = generatePublicFolderAcl('./', ownerFromChild);
   await storage.write(`${podPath}public/.acl`, serializeAcl(publicAcl));
 
   // Profile documents must be publicly readable for WebID verification
-  const profileAcl = generatePublicFolderAcl('./', webId);
+  const profileAcl = generatePublicFolderAcl('./', ownerFromProfile);
   await storage.write(`${podPath}profile/.acl`, serializeAcl(profileAcl));
 
   // Initialize storage quota if configured
diff --git a/src/server.js b/src/server.js
@@ -964,30 +964,36 @@ export function createServer(options = {}) {
     const privateTypeIndex = generateTypeIndex(`${podUri}settings/privateTypeIndex.jsonld`, { listed: false });
     await storage.write('/settings/privateTypeIndex.jsonld', serialize(privateTypeIndex));
 
-    // ACL files. Each .acl uses './' (or a relative basename for resource
-    // ACLs) so the pod isn't host-locked to whichever interface the server
-    // happened to bind on first start. The parser resolves these against
-    // the .acl's own request URL — see #428.
-    const rootAcl = generateOwnerAcl('./', webId, true);
+    // ACL files. Both `accessTo` (#428) and `acl:agent` (#430) are written
+    // relatively so the on-disk pod isn't host-locked to whichever interface
+    // the server happened to bind on first start. New single-user pods only
+    // ever use the modern card.jsonld profile layout (legacy `card` pods
+    // are detected and skipped in the caller), so the relative WebID is
+    // safe to hardcode.
+    const ownerFromRoot = './profile/card.jsonld#me';
+    const ownerFromChild = '../profile/card.jsonld#me';
+    const ownerFromProfile = './card.jsonld#me';
+
+    const rootAcl = generateOwnerAcl('./', ownerFromRoot, true);
     await storage.write('/.acl', serializeAcl(rootAcl));
 
-    const privateAcl = generatePrivateAcl('./', webId);
+    const privateAcl = generatePrivateAcl('./', ownerFromChild);
     await storage.write('/private/.acl', serializeAcl(privateAcl));
 
-    const settingsAcl = generatePrivateAcl('./', webId);
+    const settingsAcl = generatePrivateAcl('./', ownerFromChild);
     await storage.write('/settings/.acl', serializeAcl(settingsAcl));
 
     // publicTypeIndex: public read, overrides the private default inherited from /settings/
-    const publicTypeIndexAcl = generateOwnerAcl('./publicTypeIndex.jsonld', webId, false);
+    const publicTypeIndexAcl = generateOwnerAcl('./publicTypeIndex.jsonld', ownerFromChild, false);
     await storage.write('/settings/publicTypeIndex.jsonld.acl', serializeAcl(publicTypeIndexAcl));
 
-    const inboxAcl = generateInboxAcl('./', webId);
+    const inboxAcl = generateInboxAcl('./', ownerFromChild);
     await storage.write('/inbox/.acl', serializeAcl(inboxAcl));
 
-    const publicAcl = generatePublicFolderAcl('./', webId);
+    const publicAcl = generatePublicFolderAcl('./', ownerFromChild);
     await storage.write('/public/.acl', serializeAcl(publicAcl));
 
-    const profileAcl = generatePublicFolderAcl('./', webId);
+    const profileAcl = generatePublicFolderAcl('./', ownerFromProfile);
     await storage.write('/profile/.acl', serializeAcl(profileAcl));
 
     // Note: Quota not initialized for root-level pods (no user directory)
diff --git a/src/wac/parser.js b/src/wac/parser.js
@@ -242,8 +242,10 @@ export function generatePublicReadAcl(resourceUrl) {
  * Generate a full owner ACL (owner has full control, public read)
  * @param {string} resourceUrl - URL of the resource. May be relative (see
  *   `generatePublicReadAcl`).
- * @param {string} ownerWebId - WebID of the owner. Currently absolute;
- *   relative agent WebIDs are tracked in #427 Phase 2.
+ * @param {string} ownerWebId - WebID of the owner. May also be relative
+ *   (e.g. './profile/card.jsonld#me' for an in-pod owner) — the parser
+ *   resolves it against the .acl URL at check time. The profile document
+ *   itself still publishes the absolute WebID. See #430.
  * @param {boolean} isContainer - Whether this is a container
  * @returns {object} JSON-LD ACL document
  */
@@ -290,8 +292,10 @@ export function generateOwnerAcl(resourceUrl, ownerWebId, isContainer = false) {
 
 /**
  * Generate a private ACL (owner only, no public access)
- * @param {string} resourceUrl - URL of the resource
- * @param {string} ownerWebId - WebID of the owner
+ * @param {string} resourceUrl - URL of the resource (may be relative — see
+ *   `generatePublicReadAcl`).
+ * @param {string} ownerWebId - WebID of the owner (may be relative — see
+ *   `generateOwnerAcl`).
  * @param {boolean} isContainer - Whether this is a container
  * @returns {object} JSON-LD ACL document
  */
@@ -323,8 +327,8 @@ export function generatePrivateAcl(resourceUrl, ownerWebId, isContainer = true)
 
 /**
  * Generate an inbox ACL (owner full control, public append)
- * @param {string} resourceUrl - URL of the inbox
- * @param {string} ownerWebId - WebID of the owner
+ * @param {string} resourceUrl - URL of the inbox (may be relative).
+ * @param {string} ownerWebId - WebID of the owner (may be relative).
  * @returns {object} JSON-LD ACL document
  */
 export function generateInboxAcl(resourceUrl, ownerWebId) {
@@ -363,8 +367,8 @@ export function generateInboxAcl(resourceUrl, ownerWebId) {
 /**
  * Generate a public folder ACL (owner full control, public read with inheritance)
  * Used for /public/ folders where content should be publicly readable
- * @param {string} resourceUrl - URL of the folder
- * @param {string} ownerWebId - WebID of the owner
+ * @param {string} resourceUrl - URL of the folder (may be relative).
+ * @param {string} ownerWebId - WebID of the owner (may be relative).
  * @returns {object} JSON-LD ACL document
  */
 export function generatePublicFolderAcl(resourceUrl, ownerWebId) {
diff --git a/test/wac.test.js b/test/wac.test.js
@@ -296,6 +296,61 @@ describe('WAC Parser', () => {
       );
     });
 
+    // Phase 2 of #427 (#430): generators should also preserve a relative
+    // ownerWebId verbatim, so the on-disk pod is host-portable for the
+    // owner half of the rule too. The parser already resolves relative
+    // agents (PR #65 / #64) — this just exercises the writer side.
+    it('generateOwnerAcl preserves a relative ownerWebId (#430)', () => {
+      const acl = generateOwnerAcl('./', './profile/card.jsonld#me', true);
+      const owner = acl['@graph'].find(a => a['@id'] === '#owner');
+      assert.strictEqual(owner['acl:agent']['@id'], './profile/card.jsonld#me');
+    });
+
+    it('generatePrivateAcl preserves a relative ownerWebId (#430)', () => {
+      const acl = generatePrivateAcl('./', '../profile/card.jsonld#me');
+      assert.strictEqual(acl['@graph'][0]['acl:agent']['@id'], '../profile/card.jsonld#me');
+    });
+
+    it('generateInboxAcl preserves a relative ownerWebId (#430)', () => {
+      const acl = generateInboxAcl('./', '../profile/card.jsonld#me');
+      const owner = acl['@graph'].find(a => a['@id'] === '#owner');
+      assert.strictEqual(owner['acl:agent']['@id'], '../profile/card.jsonld#me');
+    });
+
+    it('generatePublicFolderAcl preserves a relative ownerWebId (#430)', () => {
+      const acl = generatePublicFolderAcl('./', './card.jsonld#me');
+      const owner = acl['@graph'].find(a => a['@id'] === '#owner');
+      assert.strictEqual(owner['acl:agent']['@id'], './card.jsonld#me');
+    });
+
+    it('round-trip: relative ownerWebId resolves to .acl base URL on parse (#430)', async () => {
+      // Same ACL document, two hosts — agent should resolve to whichever
+      // host asked, just like accessTo. This is what makes the on-disk
+      // pod portable for the owner half.
+      const generated = generateOwnerAcl('./', './profile/card.jsonld#me', true);
+      const wire = serializeAcl(generated);
+      const auths1 = await parseAcl(wire, 'http://localhost:4444/.acl');
+      const auths2 = await parseAcl(wire, 'http://0.0.0.0:4444/.acl');
+      const owner1 = auths1.find(a => a.id === '#owner');
+      const owner2 = auths2.find(a => a.id === '#owner');
+      assert.ok(owner1.agents.includes('http://localhost:4444/profile/card.jsonld#me'),
+        `Expected localhost agent, got: ${JSON.stringify(owner1.agents)}`);
+      assert.ok(owner2.agents.includes('http://0.0.0.0:4444/profile/card.jsonld#me'),
+        `Expected 0.0.0.0 agent, got: ${JSON.stringify(owner2.agents)}`);
+    });
+
+    it('round-trip: relative ownerWebId from a child folder resolves correctly (#430)', async () => {
+      // /pod/private/.acl with agent '../profile/card.jsonld#me'
+      // should resolve to /pod/profile/card.jsonld#me, not into the
+      // pod root or escape it.
+      const generated = generatePrivateAcl('./', '../profile/card.jsonld#me');
+      const wire = serializeAcl(generated);
+      const auths = await parseAcl(wire, 'http://localhost:4444/alice/private/.acl');
+      const owner = auths.find(a => a.id === '#owner');
+      assert.ok(owner.agents.includes('http://localhost:4444/alice/profile/card.jsonld#me'),
+        `Expected resolution to /alice/profile/card.jsonld#me, got: ${JSON.stringify(owner.agents)}`);
+    });
+
     it('round-trip: relative "./" resolves to the .acl base URL on parse', async () => {
       const generated = generateOwnerAcl('./', webId, true);
       const wire = serializeAcl(generated);
