@aigne/aos 0.2.0-beta

package/dist/http/afs-rpc.d.cts

@@ -0,0 +1,103 @@
+import { BlockletScope } from "../scope/types.cjs";
+import { ResolveCallerFn, ResolveTrustedAfsContext } from "./auth-context.cjs";
+import { BatchLimits } from "./afs-rpc-wire.cjs";
+import { AFSRoot, CallerInfo, UploadLimits } from "@aigne/afs";
+
+//#region src/http/afs-rpc.d.ts
+interface AfsRpcHandlerOptions {
+  /** The runtime-global AFS (the projection's source). */
+  globalAFS: AFSRoot;
+  /** Roots passed to `extractBlockletFromHost` (e.g. `["afsd.io"]`). */
+  domainRoots?: string[];
+  /**
+   * Resolve a normalized Host hostname to a blocklet id via a runtime-specific alias map.
+   * Called before browser-provided `body.blocklet` / `?blocklet=` hints and
+   * before first-label extraction, so brand domains declared in `blocklet.yaml`
+   * `sites.domains` win over a guessed first label like `staging.aside.sh`.
+   *
+   * Use case: the CF Worker has `aliases.json` mapping
+   * `explorer.arcblock.io → chain-explorer`. Without this hook, the worker's
+   * pre-existing wrapper had to inject `?blocklet=<id>` into the request URL
+   * before calling the handler — see runtimes/cloudflare/src/index.ts.
+   * Now the wrapper is gone; the worker passes its alias resolver directly.
+   *
+   * The Node daemon currently has no such alias map and leaves this unset,
+   * which preserves prior behavior (first-label extraction only).
+   */
+  resolveHostAlias?: (host: string) => Promise<string | undefined> | string | undefined;
+  /** Used when neither body, query, nor Host header resolve a blocklet. */
+  fallbackBlocklet?: string;
+  /**
+   * Bound on how many distinct blocklet projections we keep in memory.
+   * 32 is plenty for typical multi-site Workers / daemons.
+   */
+  projectionCacheLimit?: number;
+  /**
+   * Where the blocklet catalog lives in the global AFS. Defaults to
+   * `/registry/blocklets`. Override only if your runtime mounts the catalog
+   * at a non-standard path.
+   */
+  registryPath?: string;
+  /** Test seam: override the projected-AFS factory. */
+  createBlockletAFS?: (blocklet: string, globalAFS: AFSRoot) => Promise<AFSRoot>;
+  /**
+   * Resolve a verified caller from the inbound request — typically wired to
+   * the auth service's cookie/JWT verifier. When unset, all calls run as
+   * anonymous.
+   *
+   * The resolved CallerInfo is merged into every op's `context` (alongside
+   * `userId` for legacy consumers), so domain actions, capability checks,
+   * and audit hooks observe a single source of truth.
+   */
+  resolveCaller?: ResolveCallerFn;
+  /**
+   * Resolve the trusted, host-controlled AFSContext slice (observability
+   * Phase 3a) — `instanceDid` (the DID Space column key) and `agentRunOrigin`.
+   * Runs after `resolveCaller`; its result OVERRIDES any client-forged value.
+   * When unset, the handler defaults to `{ instanceDid: <resolved blocklet>,
+   * agentRunOrigin: "interactive" }` so even anonymous Node requests carry an
+   * instanceDid. CF bound hosts wire this to return the real host-resolved
+   * instanceDid instead of the blocklet compat key.
+   */
+  resolveTrustedAfsContext?: ResolveTrustedAfsContext;
+  /**
+   * Optional PER-REQUEST wrapper applied AFTER the (cached, per-blocklet) base
+   * AFS is resolved and the caller is verified. Use this to overlay per-caller
+   * (`/user`), `scope:user` whole-space (`/space`), and per-session (`/tmp`)
+   * views onto the blocklet's Small World
+   * — the same overlay the WS session binding applies — so HTTP reads see an
+   * identical topology.
+   *
+   * CRITICAL: the result is NOT cached. It MUST be rebuilt per request from the
+   * verified `caller` and the request's `sessionId`, so caller A's `/user`
+   * can never leak to caller B and session X's `/tmp` can never leak to
+   * session Y. Implementations should be best-effort (return `baseAFS`
+   * unchanged on any failure) — an overlay error must not break reads.
+   */
+  overlayForRequest?: (baseAFS: AFSRoot, ctx: {
+    blocklet: string;
+    caller: CallerInfo | null;
+    sessionId: string | null;
+    scope: BlockletScope; /** Host-resolved instanceDid (present even for an anonymous caller). instance-resolve F-2. */
+    instanceDid?: string;
+  }) => AFSRoot | Promise<AFSRoot>;
+  /**
+   * Batch-op limits (afs-rpc-batch §5.2) + the pre-parse encoded body cap.
+   * Runtimes inject their tier (BATCH_LIMITS_CF / BATCH_LIMITS_NODE); unset
+   * defaults to the conservative CF table.
+   */
+  batchLimits?: BatchLimits;
+  /**
+   * Server-enforced upload caps (DID-Space upload-limits). Resolved by the
+   * runtime's single env-read point (CF `resolveSpaceBindings`, Node
+   * `resolveUploadLimits(process.env)`) and threaded into the ingest-prepare
+   * facade so it can early-reject over-size declared uploads (Phase 2). Unset
+   * defaults to the safe baseline inside the facade.
+   */
+  uploadLimits?: UploadLimits;
+}
+type AfsRpcHandler = (request: Request) => Promise<Response>;
+declare function createAfsRpcHandler(options: AfsRpcHandlerOptions): AfsRpcHandler;
+//#endregion
+export { AfsRpcHandler, AfsRpcHandlerOptions, createAfsRpcHandler };
+//# sourceMappingURL=afs-rpc.d.cts.map

package/dist/http/afs-rpc.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"afs-rpc.d.cts","names":[],"sources":["../../src/http/afs-rpc.ts"],"mappings":";;;;;;UA0FiB,oBAAA;EAmCmC;EAjClD,SAAA,EAAW,OAAA;EAiCmD;EA/B9D,WAAA;EAyCA;;;;;;;;;;;;;;;EAzBA,gBAAA,IAAoB,IAAA,aAAiB,OAAA;EA4DtB;EA1Df,gBAAA;EAgEA;;;;EA3DA,oBAAA;EAmE2B;AAG7B;;;;EAhEE,YAAA;EAgEgD;EA9DhD,iBAAA,IAAqB,QAAA,UAAkB,SAAA,EAAW,OAAA,KAAY,OAAA,CAAQ,OAAA;EA8Df;;;;;;;AAmZzD;;EAvcE,aAAA,GAAgB,eAAA;EAuc+D;;;;;;;;;EA7b/E,wBAAA,GAA2B,wBAAA;;;;;;;;;;;;;;;EAe3B,iBAAA,IACE,OAAA,EAAS,OAAA,EACT,GAAA;IACE,QAAA;IACA,MAAA,EAAQ,UAAA;IACR,SAAA;IACA,KAAA,EAAO,aAAA;IAEP,WAAA;EAAA,MAEC,OAAA,GAAU,OAAA,CAAQ,OAAA;;;;;;EAMvB,WAAA,GAAc,WAAA;;;;;;;;EAQd,YAAA,GAAe,YAAA;AAAA;AAAA,KAGL,aAAA,IAAiB,OAAA,EAAS,OAAA,KAAY,OAAA,CAAQ,QAAA;AAAA,iBAmZ1C,mBAAA,CAAoB,OAAA,EAAS,oBAAA,GAAuB,aAAA"}

package/dist/http/afs-rpc.d.mts

@@ -0,0 +1,103 @@
+import { BlockletScope } from "../scope/types.mjs";
+import { ResolveCallerFn, ResolveTrustedAfsContext } from "./auth-context.mjs";
+import { BatchLimits } from "./afs-rpc-wire.mjs";
+import { AFSRoot, CallerInfo, UploadLimits } from "@aigne/afs";
+
+//#region src/http/afs-rpc.d.ts
+interface AfsRpcHandlerOptions {
+  /** The runtime-global AFS (the projection's source). */
+  globalAFS: AFSRoot;
+  /** Roots passed to `extractBlockletFromHost` (e.g. `["afsd.io"]`). */
+  domainRoots?: string[];
+  /**
+   * Resolve a normalized Host hostname to a blocklet id via a runtime-specific alias map.
+   * Called before browser-provided `body.blocklet` / `?blocklet=` hints and
+   * before first-label extraction, so brand domains declared in `blocklet.yaml`
+   * `sites.domains` win over a guessed first label like `staging.aside.sh`.
+   *
+   * Use case: the CF Worker has `aliases.json` mapping
+   * `explorer.arcblock.io → chain-explorer`. Without this hook, the worker's
+   * pre-existing wrapper had to inject `?blocklet=<id>` into the request URL
+   * before calling the handler — see runtimes/cloudflare/src/index.ts.
+   * Now the wrapper is gone; the worker passes its alias resolver directly.
+   *
+   * The Node daemon currently has no such alias map and leaves this unset,
+   * which preserves prior behavior (first-label extraction only).
+   */
+  resolveHostAlias?: (host: string) => Promise<string | undefined> | string | undefined;
+  /** Used when neither body, query, nor Host header resolve a blocklet. */
+  fallbackBlocklet?: string;
+  /**
+   * Bound on how many distinct blocklet projections we keep in memory.
+   * 32 is plenty for typical multi-site Workers / daemons.
+   */
+  projectionCacheLimit?: number;
+  /**
+   * Where the blocklet catalog lives in the global AFS. Defaults to
+   * `/registry/blocklets`. Override only if your runtime mounts the catalog
+   * at a non-standard path.
+   */
+  registryPath?: string;
+  /** Test seam: override the projected-AFS factory. */
+  createBlockletAFS?: (blocklet: string, globalAFS: AFSRoot) => Promise<AFSRoot>;
+  /**
+   * Resolve a verified caller from the inbound request — typically wired to
+   * the auth service's cookie/JWT verifier. When unset, all calls run as
+   * anonymous.
+   *
+   * The resolved CallerInfo is merged into every op's `context` (alongside
+   * `userId` for legacy consumers), so domain actions, capability checks,
+   * and audit hooks observe a single source of truth.
+   */
+  resolveCaller?: ResolveCallerFn;
+  /**
+   * Resolve the trusted, host-controlled AFSContext slice (observability
+   * Phase 3a) — `instanceDid` (the DID Space column key) and `agentRunOrigin`.
+   * Runs after `resolveCaller`; its result OVERRIDES any client-forged value.
+   * When unset, the handler defaults to `{ instanceDid: <resolved blocklet>,
+   * agentRunOrigin: "interactive" }` so even anonymous Node requests carry an
+   * instanceDid. CF bound hosts wire this to return the real host-resolved
+   * instanceDid instead of the blocklet compat key.
+   */
+  resolveTrustedAfsContext?: ResolveTrustedAfsContext;
+  /**
+   * Optional PER-REQUEST wrapper applied AFTER the (cached, per-blocklet) base
+   * AFS is resolved and the caller is verified. Use this to overlay per-caller
+   * (`/user`), `scope:user` whole-space (`/space`), and per-session (`/tmp`)
+   * views onto the blocklet's Small World
+   * — the same overlay the WS session binding applies — so HTTP reads see an
+   * identical topology.
+   *
+   * CRITICAL: the result is NOT cached. It MUST be rebuilt per request from the
+   * verified `caller` and the request's `sessionId`, so caller A's `/user`
+   * can never leak to caller B and session X's `/tmp` can never leak to
+   * session Y. Implementations should be best-effort (return `baseAFS`
+   * unchanged on any failure) — an overlay error must not break reads.
+   */
+  overlayForRequest?: (baseAFS: AFSRoot, ctx: {
+    blocklet: string;
+    caller: CallerInfo | null;
+    sessionId: string | null;
+    scope: BlockletScope; /** Host-resolved instanceDid (present even for an anonymous caller). instance-resolve F-2. */
+    instanceDid?: string;
+  }) => AFSRoot | Promise<AFSRoot>;
+  /**
+   * Batch-op limits (afs-rpc-batch §5.2) + the pre-parse encoded body cap.
+   * Runtimes inject their tier (BATCH_LIMITS_CF / BATCH_LIMITS_NODE); unset
+   * defaults to the conservative CF table.
+   */
+  batchLimits?: BatchLimits;
+  /**
+   * Server-enforced upload caps (DID-Space upload-limits). Resolved by the
+   * runtime's single env-read point (CF `resolveSpaceBindings`, Node
+   * `resolveUploadLimits(process.env)`) and threaded into the ingest-prepare
+   * facade so it can early-reject over-size declared uploads (Phase 2). Unset
+   * defaults to the safe baseline inside the facade.
+   */
+  uploadLimits?: UploadLimits;
+}
+type AfsRpcHandler = (request: Request) => Promise<Response>;
+declare function createAfsRpcHandler(options: AfsRpcHandlerOptions): AfsRpcHandler;
+//#endregion
+export { AfsRpcHandler, AfsRpcHandlerOptions, createAfsRpcHandler };
+//# sourceMappingURL=afs-rpc.d.mts.map

package/dist/http/afs-rpc.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"afs-rpc.d.mts","names":[],"sources":["../../src/http/afs-rpc.ts"],"mappings":";;;;;;UA0FiB,oBAAA;EAmCmC;EAjClD,SAAA,EAAW,OAAA;EAiCmD;EA/B9D,WAAA;EAyCA;;;;;;;;;;;;;;;EAzBA,gBAAA,IAAoB,IAAA,aAAiB,OAAA;EA4DtB;EA1Df,gBAAA;EAgEA;;;;EA3DA,oBAAA;EAmE2B;AAG7B;;;;EAhEE,YAAA;EAgEgD;EA9DhD,iBAAA,IAAqB,QAAA,UAAkB,SAAA,EAAW,OAAA,KAAY,OAAA,CAAQ,OAAA;EA8Df;;;;;;;AAmZzD;;EAvcE,aAAA,GAAgB,eAAA;EAuc+D;;;;;;;;;EA7b/E,wBAAA,GAA2B,wBAAA;;;;;;;;;;;;;;;EAe3B,iBAAA,IACE,OAAA,EAAS,OAAA,EACT,GAAA;IACE,QAAA;IACA,MAAA,EAAQ,UAAA;IACR,SAAA;IACA,KAAA,EAAO,aAAA;IAEP,WAAA;EAAA,MAEC,OAAA,GAAU,OAAA,CAAQ,OAAA;;;;;;EAMvB,WAAA,GAAc,WAAA;;;;;;;;EAQd,YAAA,GAAe,YAAA;AAAA;AAAA,KAGL,aAAA,IAAiB,OAAA,EAAS,OAAA,KAAY,OAAA,CAAQ,QAAA;AAAA,iBAmZ1C,mBAAA,CAAoB,OAAA,EAAS,oBAAA,GAAuB,aAAA"}