@aigne/aos 0.2.0-beta

package/dist/scope/resolve-scoped-afs.mjs

@@ -0,0 +1,88 @@
+import { readBlockletScope } from "./read-blocklet-scope.mjs";
+import { AFSValidationError, makeNsLog } from "@aigne/afs";
+
+//#region src/scope/resolve-scoped-afs.ts
+/**
+* Single source of truth for "given a blocklet, which AFS serves its requests?".
+*
+* Routing rules:
+*   scope: root  → globalAFS pass-through, no activation, no wrapping
+*   scope: app   → activator.ensureActivated() → runtime AFS
+*   scope: user  → same as app; caller data is overlaid per session by SessionUserAFS
+*   scope: agent → same as app
+*
+* Failure modes (graceful, never throw on activation failure):
+*   - Activator missing for non-root scope → log warn, fall back to globalAFS
+*   - Activator returns null → log warn, fall back to globalAFS
+*
+* Adversarial: invalid blocklet names (path traversal, separators, null bytes,
+* empty strings) reject synchronously before any I/O.
+*
+* Concurrency: parallel calls for the same (activator, blocklet) share a single
+* activation promise so the activator is invoked at most once under contention.
+*/
+const log = makeNsLog("aos");
+const BLOCKLET_NAME_RE = /^[A-Za-z0-9._-]+$/;
+function validateBlockletName(name) {
+	if (typeof name !== "string" || name.length === 0) throw new AFSValidationError("Invalid blocklet name: empty or non-string");
+	if (name.includes("/") || name.includes("\\") || name.includes("\0")) throw new AFSValidationError(`Invalid blocklet name: contains path separator or null byte (${JSON.stringify(name)})`);
+	if (name === "." || name === "..") throw new AFSValidationError(`Invalid blocklet name: reserved (${JSON.stringify(name)})`);
+	if (!BLOCKLET_NAME_RE.test(name)) throw new AFSValidationError(`Invalid blocklet name: must match ${BLOCKLET_NAME_RE} (${JSON.stringify(name)})`);
+}
+const activationLocks = /* @__PURE__ */ new WeakMap();
+function activateOnce(activator, blockletName) {
+	let perActivator = activationLocks.get(activator);
+	if (!perActivator) {
+		perActivator = /* @__PURE__ */ new Map();
+		activationLocks.set(activator, perActivator);
+	}
+	const inflight = perActivator.get(blockletName);
+	if (inflight) return inflight;
+	const promise = (async () => {
+		try {
+			return await activator.ensureActivated(blockletName);
+		} finally {
+			Promise.resolve().then(() => {
+				perActivator.delete(blockletName);
+			});
+		}
+	})();
+	perActivator.set(blockletName, promise);
+	return promise;
+}
+async function resolveScopedAFS(input) {
+	const { globalAFS, blockletName, activator } = input;
+	validateBlockletName(blockletName);
+	const scope = input.scope ?? await readBlockletScope(globalAFS, blockletName);
+	if (scope === "root") return {
+		afs: globalAFS,
+		scope: "root",
+		isGlobal: true
+	};
+	if (!activator) {
+		log.warn(`[resolveScopedAFS] no activator provided for blocklet=${blockletName} scope=${scope}; falling back to globalAFS`);
+		return {
+			afs: globalAFS,
+			scope,
+			isGlobal: true
+		};
+	}
+	const runtimeAFS = await activateOnce(activator, blockletName);
+	if (!runtimeAFS) {
+		log.warn(`[resolveScopedAFS] activator returned null for blocklet=${blockletName} scope=${scope}; falling back to globalAFS`);
+		return {
+			afs: globalAFS,
+			scope,
+			isGlobal: true
+		};
+	}
+	return {
+		afs: runtimeAFS,
+		scope,
+		isGlobal: false
+	};
+}
+
+//#endregion
+export { resolveScopedAFS };
+//# sourceMappingURL=resolve-scoped-afs.mjs.map

package/dist/scope/resolve-scoped-afs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-scoped-afs.mjs","names":[],"sources":["../../src/scope/resolve-scoped-afs.ts"],"sourcesContent":["/**\n * Single source of truth for \"given a blocklet, which AFS serves its requests?\".\n *\n * Routing rules:\n *   scope: root  → globalAFS pass-through, no activation, no wrapping\n *   scope: app   → activator.ensureActivated() → runtime AFS\n *   scope: user  → same as app; caller data is overlaid per session by SessionUserAFS\n *   scope: agent → same as app\n *\n * Failure modes (graceful, never throw on activation failure):\n *   - Activator missing for non-root scope → log warn, fall back to globalAFS\n *   - Activator returns null → log warn, fall back to globalAFS\n *\n * Adversarial: invalid blocklet names (path traversal, separators, null bytes,\n * empty strings) reject synchronously before any I/O.\n *\n * Concurrency: parallel calls for the same (activator, blocklet) share a single\n * activation promise so the activator is invoked at most once under contention.\n */\n\nimport { type AFSRoot, AFSValidationError, makeNsLog } from \"@aigne/afs\";\nimport { readBlockletScope } from \"./read-blocklet-scope.js\";\nimport type {\n  BlockletScope,\n  ResolveScopedAFSInput,\n  ResolveScopedAFSResult,\n  ScopeActivator,\n} from \"./types.js\";\n\nconst log = makeNsLog(\"aos\");\n\nconst BLOCKLET_NAME_RE = /^[A-Za-z0-9._-]+$/;\n\nfunction validateBlockletName(name: unknown): asserts name is string {\n  if (typeof name !== \"string\" || name.length === 0) {\n    throw new AFSValidationError(\"Invalid blocklet name: empty or non-string\");\n  }\n  if (name.includes(\"/\") || name.includes(\"\\\\\") || name.includes(\"\\0\")) {\n    throw new AFSValidationError(\n      `Invalid blocklet name: contains path separator or null byte (${JSON.stringify(name)})`,\n    );\n  }\n  if (name === \".\" || name === \"..\") {\n    throw new AFSValidationError(`Invalid blocklet name: reserved (${JSON.stringify(name)})`);\n  }\n  if (!BLOCKLET_NAME_RE.test(name)) {\n    throw new AFSValidationError(\n      `Invalid blocklet name: must match ${BLOCKLET_NAME_RE} (${JSON.stringify(name)})`,\n    );\n  }\n}\n\nconst activationLocks = new WeakMap<ScopeActivator, Map<string, Promise<AFSRoot | null>>>();\n\nfunction activateOnce(activator: ScopeActivator, blockletName: string): Promise<AFSRoot | null> {\n  let perActivator = activationLocks.get(activator);\n  if (!perActivator) {\n    perActivator = new Map();\n    activationLocks.set(activator, perActivator);\n  }\n  const inflight = perActivator.get(blockletName);\n  if (inflight) return inflight;\n\n  const promise = (async () => {\n    try {\n      return await activator.ensureActivated(blockletName);\n    } finally {\n      Promise.resolve().then(() => {\n        perActivator.delete(blockletName);\n      });\n    }\n  })();\n  perActivator.set(blockletName, promise);\n  return promise;\n}\n\nexport async function resolveScopedAFS(\n  input: ResolveScopedAFSInput,\n): Promise<ResolveScopedAFSResult> {\n  const { globalAFS, blockletName, activator } = input;\n  validateBlockletName(blockletName);\n\n  const scope: BlockletScope = input.scope ?? (await readBlockletScope(globalAFS, blockletName));\n\n  if (scope === \"root\") {\n    return { afs: globalAFS, scope: \"root\", isGlobal: true };\n  }\n\n  if (!activator) {\n    log.warn(\n      `[resolveScopedAFS] no activator provided for blocklet=${blockletName} scope=${scope}; falling back to globalAFS`,\n    );\n    return { afs: globalAFS, scope, isGlobal: true };\n  }\n\n  const runtimeAFS = await activateOnce(activator, blockletName);\n  if (!runtimeAFS) {\n    log.warn(\n      `[resolveScopedAFS] activator returned null for blocklet=${blockletName} scope=${scope}; falling back to globalAFS`,\n    );\n    return { afs: globalAFS, scope, isGlobal: true };\n  }\n\n  return { afs: runtimeAFS, scope, isGlobal: false };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAM,MAAM,UAAU,MAAM;AAE5B,MAAM,mBAAmB;AAEzB,SAAS,qBAAqB,MAAuC;AACnE,KAAI,OAAO,SAAS,YAAY,KAAK,WAAW,EAC9C,OAAM,IAAI,mBAAmB,6CAA6C;AAE5E,KAAI,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,KAAK,IAAI,KAAK,SAAS,KAAK,CAClE,OAAM,IAAI,mBACR,gEAAgE,KAAK,UAAU,KAAK,CAAC,GACtF;AAEH,KAAI,SAAS,OAAO,SAAS,KAC3B,OAAM,IAAI,mBAAmB,oCAAoC,KAAK,UAAU,KAAK,CAAC,GAAG;AAE3F,KAAI,CAAC,iBAAiB,KAAK,KAAK,CAC9B,OAAM,IAAI,mBACR,qCAAqC,iBAAiB,IAAI,KAAK,UAAU,KAAK,CAAC,GAChF;;AAIL,MAAM,kCAAkB,IAAI,SAA+D;AAE3F,SAAS,aAAa,WAA2B,cAA+C;CAC9F,IAAI,eAAe,gBAAgB,IAAI,UAAU;AACjD,KAAI,CAAC,cAAc;AACjB,iCAAe,IAAI,KAAK;AACxB,kBAAgB,IAAI,WAAW,aAAa;;CAE9C,MAAM,WAAW,aAAa,IAAI,aAAa;AAC/C,KAAI,SAAU,QAAO;CAErB,MAAM,WAAW,YAAY;AAC3B,MAAI;AACF,UAAO,MAAM,UAAU,gBAAgB,aAAa;YAC5C;AACR,WAAQ,SAAS,CAAC,WAAW;AAC3B,iBAAa,OAAO,aAAa;KACjC;;KAEF;AACJ,cAAa,IAAI,cAAc,QAAQ;AACvC,QAAO;;AAGT,eAAsB,iBACpB,OACiC;CACjC,MAAM,EAAE,WAAW,cAAc,cAAc;AAC/C,sBAAqB,aAAa;CAElC,MAAM,QAAuB,MAAM,SAAU,MAAM,kBAAkB,WAAW,aAAa;AAE7F,KAAI,UAAU,OACZ,QAAO;EAAE,KAAK;EAAW,OAAO;EAAQ,UAAU;EAAM;AAG1D,KAAI,CAAC,WAAW;AACd,MAAI,KACF,yDAAyD,aAAa,SAAS,MAAM,6BACtF;AACD,SAAO;GAAE,KAAK;GAAW;GAAO,UAAU;GAAM;;CAGlD,MAAM,aAAa,MAAM,aAAa,WAAW,aAAa;AAC9D,KAAI,CAAC,YAAY;AACf,MAAI,KACF,2DAA2D,aAAa,SAAS,MAAM,6BACxF;AACD,SAAO;GAAE,KAAK;GAAW;GAAO,UAAU;GAAM;;AAGlD,QAAO;EAAE,KAAK;EAAY;EAAO,UAAU;EAAO"}

package/dist/scope/types.d.cts

@@ -0,0 +1,25 @@
+import { AFSRoot } from "@aigne/afs";
+
+//#region src/scope/types.d.ts
+type BlockletScope = "root" | "app" | "user" | "agent";
+interface ScopeActivator {
+  /** Return the activated runtime AFS for blocklet, activating if necessary. Returns null on failure. */
+  ensureActivated(blockletName: string): Promise<AFSRoot | null>;
+}
+interface ResolveScopedAFSInput {
+  globalAFS: AFSRoot;
+  blockletName: string;
+  /** Pre-parsed scope. If absent, resolver reads /registry/blocklets/<name>/blocklet.yaml via globalAFS. */
+  scope?: BlockletScope;
+  /** Required for app/user/agent. Optional only when scope is known to be "root". */
+  activator?: ScopeActivator;
+}
+interface ResolveScopedAFSResult {
+  afs: AFSRoot;
+  scope: BlockletScope;
+  /** True iff afs === globalAFS (i.e. scope: root pass-through). */
+  isGlobal: boolean;
+}
+//#endregion
+export { BlockletScope, ResolveScopedAFSInput, ResolveScopedAFSResult, ScopeActivator };
+//# sourceMappingURL=types.d.cts.map

package/dist/scope/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/scope/types.ts"],"mappings":";;;KAQY,aAAA;AAAA,UAEK,cAAA;EAAA;EAEf,eAAA,CAAgB,YAAA,WAAuB,OAAA,CAAQ,OAAA;AAAA;AAAA,UAGhC,qBAAA;EACf,SAAA,EAAW,OAAA;EACX,YAAA;EALuC;EAOvC,KAAA,GAAQ,aAAA;EAP8C;EAStD,SAAA,GAAY,cAAA;AAAA;AAAA,UAGG,sBAAA;EACf,GAAA,EAAK,OAAA;EACL,KAAA,EAAO,aAAA;EAPC;EASR,QAAA;AAAA"}

package/dist/scope/types.d.mts

@@ -0,0 +1,25 @@
+import { AFSRoot } from "@aigne/afs";
+
+//#region src/scope/types.d.ts
+type BlockletScope = "root" | "app" | "user" | "agent";
+interface ScopeActivator {
+  /** Return the activated runtime AFS for blocklet, activating if necessary. Returns null on failure. */
+  ensureActivated(blockletName: string): Promise<AFSRoot | null>;
+}
+interface ResolveScopedAFSInput {
+  globalAFS: AFSRoot;
+  blockletName: string;
+  /** Pre-parsed scope. If absent, resolver reads /registry/blocklets/<name>/blocklet.yaml via globalAFS. */
+  scope?: BlockletScope;
+  /** Required for app/user/agent. Optional only when scope is known to be "root". */
+  activator?: ScopeActivator;
+}
+interface ResolveScopedAFSResult {
+  afs: AFSRoot;
+  scope: BlockletScope;
+  /** True iff afs === globalAFS (i.e. scope: root pass-through). */
+  isGlobal: boolean;
+}
+//#endregion
+export { BlockletScope, ResolveScopedAFSInput, ResolveScopedAFSResult, ScopeActivator };
+//# sourceMappingURL=types.d.mts.map

package/dist/scope/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/scope/types.ts"],"mappings":";;;KAQY,aAAA;AAAA,UAEK,cAAA;EAAA;EAEf,eAAA,CAAgB,YAAA,WAAuB,OAAA,CAAQ,OAAA;AAAA;AAAA,UAGhC,qBAAA;EACf,SAAA,EAAW,OAAA;EACX,YAAA;EALuC;EAOvC,KAAA,GAAQ,aAAA;EAP8C;EAStD,SAAA,GAAY,cAAA;AAAA;AAAA,UAGG,sBAAA;EACf,GAAA,EAAK,OAAA;EACL,KAAA,EAAO,aAAA;EAPC;EASR,QAAA;AAAA"}

package/dist/session/backends.cjs

@@ -0,0 +1,90 @@
+const require_session_id = require('./session-id.cjs');
+let ufo = require("ufo");
+let _aigne_afs = require("@aigne/afs");
+
+//#region src/session/backends.ts
+/**
+* Per-user / per-session / whole-user-space AFS backend factory builders.
+*
+* Both are thin: given a `DIDSpaceLike` (local `DIDSpace` or `CloudflareDIDSpace`)
+* they return a factory that projects the right slice of a role-scoped instance
+* space. Runtime-agnostic — the Node daemon (afs-loader) and the CF Worker
+* (Phase 7) build them from their own DID Space implementation, so neither
+* reimplements the projection shape (blocklet-structure.md §4.4 / §6.2).
+*/
+const READ_ONLY_SPACE_OPS = new Set([
+	"list",
+	"read",
+	"query",
+	"stat",
+	"search",
+	"explain"
+]);
+/**
+* Build the per-user data backend: projects a single user's content root inside
+* the instance via `getInstanceSpace({ role: "user", userDid })`. Mounted by the
+* runtime at `/blocklets/<name>/users/<did>/` and surfaced in-session as `/user`.
+*
+* Takes a `SpaceResolver` (not a single space) so WHICH space backs the user is
+* decided per-call: `resolveUserSpace(userDid)` returns the caller's OWN space.
+* The user fragment inside it is the single `blocklets/<i>/user` subtree —
+* `userDid` is NOT passed to `getInstanceSpace` (the space already IS the
+* user's; addressing by userDid would be redundant, and it's @deprecated there).
+*/
+function createUserDataBackend(resolver) {
+	return async (instanceDid, userDid) => {
+		return new _aigne_afs.ProjectionProvider({
+			name: "user-data",
+			globalAFS: await (await resolver.resolveUserSpace(userDid)).getInstanceSpace({
+				instanceDid,
+				role: "user"
+			}),
+			sourcePath: "/"
+		});
+	};
+}
+/**
+* Build the per-session scratch backend: pins to the system instance space's
+* `/sessions/<sid>/tmp` sub-corner. Rejects unsafe session ids (defense-in-depth
+* so the sub-path can never escape that corner). Session scratch is always
+* installer-side data, so it resolves via `resolveInstallerSpace()`.
+*/
+function createSessionTmpBackend(resolver) {
+	return async (instanceDid, sessionId) => {
+		if (!require_session_id.isValidSessionId(sessionId)) throw new Error(`sessionTmpBackend: invalid sessionId ${JSON.stringify(sessionId)}`);
+		return new _aigne_afs.ProjectionProvider({
+			name: "session-tmp",
+			globalAFS: await (await resolver.resolveInstallerSpace()).getInstanceSpace({
+				instanceDid,
+				role: "system"
+			}),
+			sourcePath: (0, ufo.joinURL)("/sessions", sessionId, "tmp")
+		});
+	};
+}
+/**
+* Build the caller's whole DID Space root backend, surfaced in-session as
+* `/space` for `scope:user` blocklets.
+*
+* This is intentionally separate from `/user`: `/user` is the current blocklet's
+* per-user fragment (`blocklets/<i>/user`), while `/space` is the caller's whole
+* DID Space root. Default readonly keeps `scope:user` from becoming a blanket
+* write capability.
+*/
+function createUserSpaceRootBackend(resolver) {
+	return async (userDid, accessMode = "readonly") => {
+		const space = await resolver.resolveUserSpace(userDid);
+		if (typeof space.getSpaceRoot !== "function") throw new Error("user DID Space backend does not expose getSpaceRoot()");
+		return new _aigne_afs.ProjectionProvider({
+			name: "user-space-root",
+			globalAFS: await space.getSpaceRoot({ accessMode }),
+			sourcePath: "/",
+			allowedOps: accessMode === "readonly" ? READ_ONLY_SPACE_OPS : void 0
+		});
+	};
+}
+
+//#endregion
+exports.createSessionTmpBackend = createSessionTmpBackend;
+exports.createUserDataBackend = createUserDataBackend;
+exports.createUserSpaceRootBackend = createUserSpaceRootBackend;

package/dist/session/backends.d.cts

@@ -0,0 +1,35 @@
+import { AFSAccessMode, AFSModule, SpaceResolver } from "@aigne/afs";
+
+//#region src/session/backends.d.ts
+/**
+ * Build the per-user data backend: projects a single user's content root inside
+ * the instance via `getInstanceSpace({ role: "user", userDid })`. Mounted by the
+ * runtime at `/blocklets/<name>/users/<did>/` and surfaced in-session as `/user`.
+ *
+ * Takes a `SpaceResolver` (not a single space) so WHICH space backs the user is
+ * decided per-call: `resolveUserSpace(userDid)` returns the caller's OWN space.
+ * The user fragment inside it is the single `blocklets/<i>/user` subtree —
+ * `userDid` is NOT passed to `getInstanceSpace` (the space already IS the
+ * user's; addressing by userDid would be redundant, and it's @deprecated there).
+ */
+declare function createUserDataBackend(resolver: SpaceResolver): (instanceDid: string, userDid: string) => Promise<AFSModule>;
+/**
+ * Build the per-session scratch backend: pins to the system instance space's
+ * `/sessions/<sid>/tmp` sub-corner. Rejects unsafe session ids (defense-in-depth
+ * so the sub-path can never escape that corner). Session scratch is always
+ * installer-side data, so it resolves via `resolveInstallerSpace()`.
+ */
+declare function createSessionTmpBackend(resolver: SpaceResolver): (instanceDid: string, sessionId: string) => Promise<AFSModule>;
+/**
+ * Build the caller's whole DID Space root backend, surfaced in-session as
+ * `/space` for `scope:user` blocklets.
+ *
+ * This is intentionally separate from `/user`: `/user` is the current blocklet's
+ * per-user fragment (`blocklets/<i>/user`), while `/space` is the caller's whole
+ * DID Space root. Default readonly keeps `scope:user` from becoming a blanket
+ * write capability.
+ */
+declare function createUserSpaceRootBackend(resolver: SpaceResolver): (userDid: string, accessMode?: AFSAccessMode) => Promise<AFSModule>;
+//#endregion
+export { createSessionTmpBackend, createUserDataBackend, createUserSpaceRootBackend };
+//# sourceMappingURL=backends.d.cts.map

package/dist/session/backends.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backends.d.cts","names":[],"sources":["../../src/session/backends.ts"],"mappings":";;;;;;;;;;;;AAkDA;;iBAjBgB,qBAAA,CACd,QAAA,EAAU,aAAA,IACR,WAAA,UAAqB,OAAA,aAAoB,OAAA,CAAQ,SAAA;;;;;;;iBAerC,uBAAA,CACd,QAAA,EAAU,aAAA,IACR,WAAA,UAAqB,SAAA,aAAsB,OAAA,CAAQ,SAAA;;;;;;;AA0BvD;;;iBAAgB,0BAAA,CACd,QAAA,EAAU,aAAA,IACR,OAAA,UAAiB,UAAA,GAAa,aAAA,KAAkB,OAAA,CAAQ,SAAA"}

package/dist/session/backends.d.mts

@@ -0,0 +1,35 @@
+import { AFSAccessMode, AFSModule, SpaceResolver } from "@aigne/afs";
+
+//#region src/session/backends.d.ts
+/**
+ * Build the per-user data backend: projects a single user's content root inside
+ * the instance via `getInstanceSpace({ role: "user", userDid })`. Mounted by the
+ * runtime at `/blocklets/<name>/users/<did>/` and surfaced in-session as `/user`.
+ *
+ * Takes a `SpaceResolver` (not a single space) so WHICH space backs the user is
+ * decided per-call: `resolveUserSpace(userDid)` returns the caller's OWN space.
+ * The user fragment inside it is the single `blocklets/<i>/user` subtree —
+ * `userDid` is NOT passed to `getInstanceSpace` (the space already IS the
+ * user's; addressing by userDid would be redundant, and it's @deprecated there).
+ */
+declare function createUserDataBackend(resolver: SpaceResolver): (instanceDid: string, userDid: string) => Promise<AFSModule>;
+/**
+ * Build the per-session scratch backend: pins to the system instance space's
+ * `/sessions/<sid>/tmp` sub-corner. Rejects unsafe session ids (defense-in-depth
+ * so the sub-path can never escape that corner). Session scratch is always
+ * installer-side data, so it resolves via `resolveInstallerSpace()`.
+ */
+declare function createSessionTmpBackend(resolver: SpaceResolver): (instanceDid: string, sessionId: string) => Promise<AFSModule>;
+/**
+ * Build the caller's whole DID Space root backend, surfaced in-session as
+ * `/space` for `scope:user` blocklets.
+ *
+ * This is intentionally separate from `/user`: `/user` is the current blocklet's
+ * per-user fragment (`blocklets/<i>/user`), while `/space` is the caller's whole
+ * DID Space root. Default readonly keeps `scope:user` from becoming a blanket
+ * write capability.
+ */
+declare function createUserSpaceRootBackend(resolver: SpaceResolver): (userDid: string, accessMode?: AFSAccessMode) => Promise<AFSModule>;
+//#endregion
+export { createSessionTmpBackend, createUserDataBackend, createUserSpaceRootBackend };
+//# sourceMappingURL=backends.d.mts.map

package/dist/session/backends.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backends.d.mts","names":[],"sources":["../../src/session/backends.ts"],"mappings":";;;;;;;;;;;;AAkDA;;iBAjBgB,qBAAA,CACd,QAAA,EAAU,aAAA,IACR,WAAA,UAAqB,OAAA,aAAoB,OAAA,CAAQ,SAAA;;;;;;;iBAerC,uBAAA,CACd,QAAA,EAAU,aAAA,IACR,WAAA,UAAqB,SAAA,aAAsB,OAAA,CAAQ,SAAA;;;;;;;AA0BvD;;;iBAAgB,0BAAA,CACd,QAAA,EAAU,aAAA,IACR,OAAA,UAAiB,UAAA,GAAa,aAAA,KAAkB,OAAA,CAAQ,SAAA"}

package/dist/session/backends.mjs

@@ -0,0 +1,89 @@
+import { isValidSessionId } from "./session-id.mjs";
+import { joinURL } from "ufo";
+import { ProjectionProvider } from "@aigne/afs";
+
+//#region src/session/backends.ts
+/**
+* Per-user / per-session / whole-user-space AFS backend factory builders.
+*
+* Both are thin: given a `DIDSpaceLike` (local `DIDSpace` or `CloudflareDIDSpace`)
+* they return a factory that projects the right slice of a role-scoped instance
+* space. Runtime-agnostic — the Node daemon (afs-loader) and the CF Worker
+* (Phase 7) build them from their own DID Space implementation, so neither
+* reimplements the projection shape (blocklet-structure.md §4.4 / §6.2).
+*/
+const READ_ONLY_SPACE_OPS = new Set([
+	"list",
+	"read",
+	"query",
+	"stat",
+	"search",
+	"explain"
+]);
+/**
+* Build the per-user data backend: projects a single user's content root inside
+* the instance via `getInstanceSpace({ role: "user", userDid })`. Mounted by the
+* runtime at `/blocklets/<name>/users/<did>/` and surfaced in-session as `/user`.
+*
+* Takes a `SpaceResolver` (not a single space) so WHICH space backs the user is
+* decided per-call: `resolveUserSpace(userDid)` returns the caller's OWN space.
+* The user fragment inside it is the single `blocklets/<i>/user` subtree —
+* `userDid` is NOT passed to `getInstanceSpace` (the space already IS the
+* user's; addressing by userDid would be redundant, and it's @deprecated there).
+*/
+function createUserDataBackend(resolver) {
+	return async (instanceDid, userDid) => {
+		return new ProjectionProvider({
+			name: "user-data",
+			globalAFS: await (await resolver.resolveUserSpace(userDid)).getInstanceSpace({
+				instanceDid,
+				role: "user"
+			}),
+			sourcePath: "/"
+		});
+	};
+}
+/**
+* Build the per-session scratch backend: pins to the system instance space's
+* `/sessions/<sid>/tmp` sub-corner. Rejects unsafe session ids (defense-in-depth
+* so the sub-path can never escape that corner). Session scratch is always
+* installer-side data, so it resolves via `resolveInstallerSpace()`.
+*/
+function createSessionTmpBackend(resolver) {
+	return async (instanceDid, sessionId) => {
+		if (!isValidSessionId(sessionId)) throw new Error(`sessionTmpBackend: invalid sessionId ${JSON.stringify(sessionId)}`);
+		return new ProjectionProvider({
+			name: "session-tmp",
+			globalAFS: await (await resolver.resolveInstallerSpace()).getInstanceSpace({
+				instanceDid,
+				role: "system"
+			}),
+			sourcePath: joinURL("/sessions", sessionId, "tmp")
+		});
+	};
+}
+/**
+* Build the caller's whole DID Space root backend, surfaced in-session as
+* `/space` for `scope:user` blocklets.
+*
+* This is intentionally separate from `/user`: `/user` is the current blocklet's
+* per-user fragment (`blocklets/<i>/user`), while `/space` is the caller's whole
+* DID Space root. Default readonly keeps `scope:user` from becoming a blanket
+* write capability.
+*/
+function createUserSpaceRootBackend(resolver) {
+	return async (userDid, accessMode = "readonly") => {
+		const space = await resolver.resolveUserSpace(userDid);
+		if (typeof space.getSpaceRoot !== "function") throw new Error("user DID Space backend does not expose getSpaceRoot()");
+		return new ProjectionProvider({
+			name: "user-space-root",
+			globalAFS: await space.getSpaceRoot({ accessMode }),
+			sourcePath: "/",
+			allowedOps: accessMode === "readonly" ? READ_ONLY_SPACE_OPS : void 0
+		});
+	};
+}
+
+//#endregion
+export { createSessionTmpBackend, createUserDataBackend, createUserSpaceRootBackend };
+//# sourceMappingURL=backends.mjs.map

package/dist/session/backends.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"backends.mjs","names":[],"sources":["../../src/session/backends.ts"],"sourcesContent":["/**\n * Per-user / per-session / whole-user-space AFS backend factory builders.\n *\n * Both are thin: given a `DIDSpaceLike` (local `DIDSpace` or `CloudflareDIDSpace`)\n * they return a factory that projects the right slice of a role-scoped instance\n * space. Runtime-agnostic — the Node daemon (afs-loader) and the CF Worker\n * (Phase 7) build them from their own DID Space implementation, so neither\n * reimplements the projection shape (blocklet-structure.md §4.4 / §6.2).\n */\n\nimport {\n  type AFSAccessMode,\n  type AFSModule,\n  ProjectionProvider,\n  type SpaceResolver,\n} from \"@aigne/afs\";\nimport { joinURL } from \"ufo\";\nimport { isValidSessionId } from \"./session-id.js\";\n\n// `query` is read-class (collection view) — readonly spaces stay queryable.\nconst READ_ONLY_SPACE_OPS = new Set([\"list\", \"read\", \"query\", \"stat\", \"search\", \"explain\"]);\n\n/**\n * Build the per-user data backend: projects a single user's content root inside\n * the instance via `getInstanceSpace({ role: \"user\", userDid })`. Mounted by the\n * runtime at `/blocklets/<name>/users/<did>/` and surfaced in-session as `/user`.\n *\n * Takes a `SpaceResolver` (not a single space) so WHICH space backs the user is\n * decided per-call: `resolveUserSpace(userDid)` returns the caller's OWN space.\n * The user fragment inside it is the single `blocklets/<i>/user` subtree —\n * `userDid` is NOT passed to `getInstanceSpace` (the space already IS the\n * user's; addressing by userDid would be redundant, and it's @deprecated there).\n */\nexport function createUserDataBackend(\n  resolver: SpaceResolver,\n): (instanceDid: string, userDid: string) => Promise<AFSModule> {\n  return async (instanceDid, userDid) => {\n    const space = await resolver.resolveUserSpace(userDid);\n    const userAFS = await space.getInstanceSpace({ instanceDid, role: \"user\" });\n    // /files-prefix-removal: getInstanceSpace content tree is the role root now.\n    return new ProjectionProvider({ name: \"user-data\", globalAFS: userAFS, sourcePath: \"/\" });\n  };\n}\n\n/**\n * Build the per-session scratch backend: pins to the system instance space's\n * `/sessions/<sid>/tmp` sub-corner. Rejects unsafe session ids (defense-in-depth\n * so the sub-path can never escape that corner). Session scratch is always\n * installer-side data, so it resolves via `resolveInstallerSpace()`.\n */\nexport function createSessionTmpBackend(\n  resolver: SpaceResolver,\n): (instanceDid: string, sessionId: string) => Promise<AFSModule> {\n  return async (instanceDid, sessionId) => {\n    if (!isValidSessionId(sessionId)) {\n      throw new Error(`sessionTmpBackend: invalid sessionId ${JSON.stringify(sessionId)}`);\n    }\n    const space = await resolver.resolveInstallerSpace();\n    const systemAFS = await space.getInstanceSpace({ instanceDid, role: \"system\" });\n    // /files-prefix-removal: content tree is the role root → sessions live at\n    // `/sessions/<sid>/tmp` (was `/files/sessions/...`).\n    return new ProjectionProvider({\n      name: \"session-tmp\",\n      globalAFS: systemAFS,\n      sourcePath: joinURL(\"/sessions\", sessionId, \"tmp\"),\n    });\n  };\n}\n\n/**\n * Build the caller's whole DID Space root backend, surfaced in-session as\n * `/space` for `scope:user` blocklets.\n *\n * This is intentionally separate from `/user`: `/user` is the current blocklet's\n * per-user fragment (`blocklets/<i>/user`), while `/space` is the caller's whole\n * DID Space root. Default readonly keeps `scope:user` from becoming a blanket\n * write capability.\n */\nexport function createUserSpaceRootBackend(\n  resolver: SpaceResolver,\n): (userDid: string, accessMode?: AFSAccessMode) => Promise<AFSModule> {\n  return async (userDid, accessMode = \"readonly\") => {\n    const space = await resolver.resolveUserSpace(userDid);\n    if (typeof space.getSpaceRoot !== \"function\") {\n      throw new Error(\"user DID Space backend does not expose getSpaceRoot()\");\n    }\n    const root = await space.getSpaceRoot({ accessMode });\n    return new ProjectionProvider({\n      name: \"user-space-root\",\n      globalAFS: root,\n      sourcePath: \"/\",\n      allowedOps: accessMode === \"readonly\" ? READ_ONLY_SPACE_OPS : undefined,\n    });\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;AAoBA,MAAM,sBAAsB,IAAI,IAAI;CAAC;CAAQ;CAAQ;CAAS;CAAQ;CAAU;CAAU,CAAC;;;;;;;;;;;;AAa3F,SAAgB,sBACd,UAC8D;AAC9D,QAAO,OAAO,aAAa,YAAY;AAIrC,SAAO,IAAI,mBAAmB;GAAE,MAAM;GAAa,WAFnC,OADF,MAAM,SAAS,iBAAiB,QAAQ,EAC1B,iBAAiB;IAAE;IAAa,MAAM;IAAQ,CAAC;GAEJ,YAAY;GAAK,CAAC;;;;;;;;;AAU7F,SAAgB,wBACd,UACgE;AAChE,QAAO,OAAO,aAAa,cAAc;AACvC,MAAI,CAAC,iBAAiB,UAAU,CAC9B,OAAM,IAAI,MAAM,wCAAwC,KAAK,UAAU,UAAU,GAAG;AAMtF,SAAO,IAAI,mBAAmB;GAC5B,MAAM;GACN,WALgB,OADJ,MAAM,SAAS,uBAAuB,EACtB,iBAAiB;IAAE;IAAa,MAAM;IAAU,CAAC;GAM7E,YAAY,QAAQ,aAAa,WAAW,MAAM;GACnD,CAAC;;;;;;;;;;;;AAaN,SAAgB,2BACd,UACqE;AACrE,QAAO,OAAO,SAAS,aAAa,eAAe;EACjD,MAAM,QAAQ,MAAM,SAAS,iBAAiB,QAAQ;AACtD,MAAI,OAAO,MAAM,iBAAiB,WAChC,OAAM,IAAI,MAAM,wDAAwD;AAG1E,SAAO,IAAI,mBAAmB;GAC5B,MAAM;GACN,WAHW,MAAM,MAAM,aAAa,EAAE,YAAY,CAAC;GAInD,YAAY;GACZ,YAAY,eAAe,aAAa,sBAAsB;GAC/D,CAAC"}