@agent-native/core 0.86.1 → 0.88.0

package/corpus/core/src/secrets/crypto.ts

@@ -16,25 +16,61 @@
  * lets readers distinguish ciphertext from legacy plaintext during migration.
  */
 
-import {
-  randomBytes,
-  createCipheriv,
-  createDecipheriv,
-  createHash,
-} from "node:crypto";
+type NodeCryptoModule = typeof import("node:crypto");
+
+function getNodeCrypto(): NodeCryptoModule | undefined {
+  if (
+    typeof window !== "undefined" ||
+    typeof process === "undefined" ||
+    !process.versions?.node ||
+    typeof process.getBuiltinModule !== "function"
+  ) {
+    return undefined;
+  }
+  return process.getBuiltinModule("node:crypto") as
+    | NodeCryptoModule
+    | undefined;
+}
+
+const nodeCrypto = getNodeCrypto();
 
 let _warnedFallback = false;
 
+function requireNodeCrypto(): NonNullable<typeof nodeCrypto> {
+  if (!nodeCrypto) {
+    throw new Error(
+      "[agent-native/secrets] Secret encryption is only available in server/runtime code.",
+    );
+  }
+  return nodeCrypto;
+}
+
+function processNodeEnv(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return process.env.NODE_ENV;
+}
+
+function processCwd(): string {
+  if (typeof process === "undefined") return ".";
+  return process.cwd();
+}
+
 /**
  * Derive a 32-byte AES key from the configured secret material via SHA-256.
  * Re-derived per call (cheap, stateless, and makes rotation easy).
  */
 export function getSecretEncryptionKey(): Buffer {
+  const { createHash } = requireNodeCrypto();
   const explicit =
-    process.env.SECRETS_ENCRYPTION_KEY || process.env.BETTER_AUTH_SECRET;
+    (typeof process === "undefined"
+      ? undefined
+      : process.env.SECRETS_ENCRYPTION_KEY) ||
+    (typeof process === "undefined"
+      ? undefined
+      : process.env.BETTER_AUTH_SECRET);
 
   if (!explicit) {
-    if (process.env.NODE_ENV === "production") {
+    if (processNodeEnv() === "production") {
       throw new Error(
         "[agent-native/secrets] Refusing to start in production without an encryption key. " +
           "Set SECRETS_ENCRYPTION_KEY (preferred) or BETTER_AUTH_SECRET in the deploy environment. " +
@@ -53,12 +89,13 @@ export function getSecretEncryptionKey(): Buffer {
     }
   }
 
-  const material = explicit || `agent-native-secrets:${process.cwd()}`;
+  const material = explicit || `agent-native-secrets:${processCwd()}`;
   return createHash("sha256").update(material).digest();
 }
 
 /** Encrypt a plain-text value. Returns `v1:<iv-hex>:<ct-hex>:<tag-hex>`. */
 export function encryptSecretValue(plaintext: string): string {
+  const { createCipheriv, randomBytes } = requireNodeCrypto();
   const key = getSecretEncryptionKey();
   const iv = randomBytes(12);
   const cipher = createCipheriv("aes-256-gcm", key, iv);
@@ -69,6 +106,7 @@ export function encryptSecretValue(plaintext: string): string {
 
 /** Decrypt a value produced by `encryptSecretValue`. Throws on tampering. */
 export function decryptSecretValue(encrypted: string): string {
+  const { createDecipheriv } = requireNodeCrypto();
   if (!encrypted.startsWith("v1:")) {
     throw new Error("Unrecognised secret encoding");
   }

package/corpus/core/src/server/action-discovery.ts

@@ -562,6 +562,10 @@ export async function mergeCoreSharingActions(
       "set-resource-visibility",
       () => import("../sharing/actions/set-resource-visibility.js"),
     ],
+    [
+      "create-agent-resource-link",
+      () => import("../sharing/actions/create-agent-resource-link.js"),
+    ],
     ["upload-image", () => import("../file-upload/actions/upload-image.js")],
     [
       "context-manifest-get",

package/corpus/core/src/server/action-routes.ts

@@ -5,6 +5,7 @@ import {
   getMethod,
   getQuery,
   getHeader,
+  getRequestURL,
 } from "h3";
 
 import { isAgentActionStopError } from "../action.js";
@@ -282,7 +283,13 @@ export function mountActionRoutes(
         const timezone = readTimezoneHeader(event);
 
         return runWithRequestContext(
-          { userEmail, userName, orgId, timezone },
+          {
+            userEmail,
+            userName,
+            orgId,
+            timezone,
+            requestOrigin: getRequestURL(event).origin,
+          },
           async () => {
             // Reject oversize bodies from Content-Length before parsing, so a
             // public no-auth POST can't force parse work on a huge request.

package/corpus/core/src/server/agent-access.ts

@@ -0,0 +1,72 @@
+import {
+  DEFAULT_AGENT_ACCESS_TTL_SECONDS,
+  scopedAgentAccessResourceId,
+  type AgentAccessResourceScope,
+} from "../shared/agent-access.js";
+import {
+  signShortLivedToken,
+  verifyShortLivedToken,
+  type VerifyResult,
+} from "./short-lived-token.js";
+
+export {
+  AGENT_ACCESS_PARAM,
+  DEFAULT_AGENT_ACCESS_TTL_SECONDS,
+  appendAgentAccessParam,
+  buildAgentAccessApiUrl,
+  buildAgentAccessUrl,
+  normalizeAgentAccessBasePath,
+  normalizeAgentAccessOrigin,
+  scopedAgentAccessResourceId,
+  toAgentAccessUrl,
+  type AgentAccessApiUrlOptions,
+  type AgentAccessResourceScope,
+  type AgentAccessUrlOptions,
+} from "../shared/agent-access.js";
+
+export interface ScopedAgentAccessTokenOptions extends AgentAccessResourceScope {
+  viewerEmail?: string;
+  ttlSeconds?: number;
+}
+
+export interface ScopedAgentAccessGrant {
+  token: string;
+  expiresAt: string;
+  ttlSeconds: number;
+}
+
+export function signScopedAgentAccessToken({
+  resourceKind,
+  resourceId,
+  viewerEmail,
+  ttlSeconds = DEFAULT_AGENT_ACCESS_TTL_SECONDS,
+}: ScopedAgentAccessTokenOptions): string {
+  return signShortLivedToken({
+    resourceId: scopedAgentAccessResourceId(resourceKind, resourceId),
+    viewerEmail,
+    ttlSeconds,
+  });
+}
+
+export function verifyScopedAgentAccessToken(
+  token: string,
+  scope: AgentAccessResourceScope,
+): VerifyResult {
+  if (!token) return { ok: false, reason: "missing" };
+  return verifyShortLivedToken(
+    token,
+    scopedAgentAccessResourceId(scope.resourceKind, scope.resourceId),
+  );
+}
+
+export function createScopedAgentAccessGrant(
+  options: ScopedAgentAccessTokenOptions,
+): ScopedAgentAccessGrant {
+  const ttlSeconds = options.ttlSeconds ?? DEFAULT_AGENT_ACCESS_TTL_SECONDS;
+  const token = signScopedAgentAccessToken({ ...options, ttlSeconds });
+  return {
+    token,
+    expiresAt: new Date(Date.now() + ttlSeconds * 1000).toISOString(),
+    ttlSeconds,
+  };
+}

package/corpus/core/src/server/h3-helpers.ts

@@ -1,5 +1,4 @@
 import type { ReadStream } from "node:fs";
-import { Readable } from "node:stream";
 
 /**
  * Small helpers around h3 v2 that polish ergonomics for templates.
@@ -158,5 +157,18 @@ export async function readBodyWithSizeLimit<T = any>(
  *   return streamFile(fs.createReadStream(filePath));
  */
 export function streamFile(stream: ReadStream): ReadableStream {
-  return Readable.toWeb(stream) as ReadableStream;
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      stream.on("data", (chunk: string | Uint8Array) => {
+        controller.enqueue(
+          typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk,
+        );
+      });
+      stream.on("end", () => controller.close());
+      stream.on("error", (error) => controller.error(error));
+    },
+    cancel() {
+      stream.destroy();
+    },
+  });
 }

package/corpus/core/src/server/index.ts

@@ -459,6 +459,34 @@ export {
   type ShortLivedTokenClaims,
   type VerifyResult as ShortLivedTokenVerifyResult,
 } from "./short-lived-token.js";
+export {
+  AGENT_ACCESS_PARAM,
+  DEFAULT_AGENT_ACCESS_TTL_SECONDS,
+  appendAgentAccessParam,
+  buildAgentAccessApiUrl,
+  buildAgentAccessUrl,
+  createScopedAgentAccessGrant,
+  normalizeAgentAccessBasePath,
+  normalizeAgentAccessOrigin,
+  scopedAgentAccessResourceId,
+  signScopedAgentAccessToken,
+  toAgentAccessUrl,
+  verifyScopedAgentAccessToken,
+  type AgentAccessApiUrlOptions,
+  type AgentAccessResourceScope,
+  type AgentAccessUrlOptions,
+  type ScopedAgentAccessGrant,
+  type ScopedAgentAccessTokenOptions,
+} from "./agent-access.js";
+export {
+  AGENT_READABLE_RESOURCE_PAYLOAD_TYPE,
+  AGENT_READABLE_RESOURCE_SCRIPT_TYPE,
+  buildAgentReadableResourceDiscovery,
+  renderAgentReadableResourceDiscoveryScript,
+  safeJsonForHtml,
+  type AgentReadableResourceDiscovery,
+  type BuildAgentReadableResourceDiscoveryOptions,
+} from "../shared/agent-readable-resource.js";
 
 // SSR handler is NOT re-exported here — it uses a virtual module
 // (virtual:react-router/server-build) that only exists at Vite dev/build time.

package/corpus/core/src/server/request-context.ts

@@ -15,7 +15,62 @@
  * process.env so existing `AGENT_USER_EMAIL=x pnpm action foo` invocations
  * continue to work.
  */
-import { AsyncLocalStorage } from "node:async_hooks";
+
+type AsyncLocalStorageLike<T> = {
+  getStore(): T | undefined;
+  run<R>(store: T, callback: () => R): R;
+};
+
+type AsyncLocalStorageCtor = new <T>() => AsyncLocalStorageLike<T>;
+
+class StackAsyncLocalStorage<T> implements AsyncLocalStorageLike<T> {
+  private readonly stack: T[] = [];
+
+  getStore(): T | undefined {
+    return this.stack.at(-1);
+  }
+
+  run<R>(store: T, callback: () => R): R {
+    this.stack.push(store);
+    try {
+      const result = callback();
+      const maybePromise = result as unknown as
+        | { finally?: (callback: () => void) => unknown }
+        | undefined;
+      if (maybePromise && typeof maybePromise.finally === "function") {
+        return maybePromise.finally(() => {
+          this.stack.pop();
+        }) as R;
+      }
+      this.stack.pop();
+      return result;
+    } catch (error) {
+      this.stack.pop();
+      throw error;
+    }
+  }
+}
+
+function getAsyncLocalStorageCtor(): AsyncLocalStorageCtor | undefined {
+  if (
+    typeof window !== "undefined" ||
+    typeof process === "undefined" ||
+    !process.versions?.node ||
+    typeof process.getBuiltinModule !== "function"
+  ) {
+    return undefined;
+  }
+  return process.getBuiltinModule("node:async_hooks")?.AsyncLocalStorage as
+    | AsyncLocalStorageCtor
+    | undefined;
+}
+
+const AsyncLocalStorageCtor = getAsyncLocalStorageCtor();
+
+function processEnv(name: string): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return process.env?.[name];
+}
 
 /**
  * Per-request agent-run state. Lives on `RequestContext.run` so the
@@ -114,12 +169,14 @@ const GLOBAL_KEY = "__agentNativeRequestContextAls" as const;
 const OBSERVERS_KEY = "__agentNativeRequestContextObservers" as const;
 type RequestContextObserver = (ctx: RequestContext) => void;
 type GlobalWithRequestContext = typeof globalThis & {
-  [GLOBAL_KEY]?: AsyncLocalStorage<RequestContext>;
+  [GLOBAL_KEY]?: AsyncLocalStorageLike<RequestContext>;
   [OBSERVERS_KEY]?: RequestContextObserver[];
 };
 const globalRef = globalThis as GlobalWithRequestContext;
 if (!globalRef[GLOBAL_KEY]) {
-  globalRef[GLOBAL_KEY] = new AsyncLocalStorage<RequestContext>();
+  globalRef[GLOBAL_KEY] = AsyncLocalStorageCtor
+    ? new AsyncLocalStorageCtor<RequestContext>()
+    : new StackAsyncLocalStorage<RequestContext>();
 }
 if (!globalRef[OBSERVERS_KEY]) {
   globalRef[OBSERVERS_KEY] = [];
@@ -211,7 +268,7 @@ export function getRequestUserEmail(): string | undefined {
     if (store.userEmail) markAuthContextAccess(store);
     return store.userEmail;
   }
-  return process.env.AGENT_USER_EMAIL;
+  return processEnv("AGENT_USER_EMAIL");
 }
 
 /**
@@ -227,7 +284,7 @@ export function getRequestUserName(): string | undefined {
     if (store.userName) markAuthContextAccess(store);
     return store.userName;
   }
-  return process.env.AGENT_USER_NAME;
+  return processEnv("AGENT_USER_NAME");
 }
 
 /**
@@ -243,7 +300,7 @@ export function getRequestOrgId(): string | undefined {
     if (store.orgId) markAuthContextAccess(store);
     return store.orgId;
   }
-  return process.env.AGENT_ORG_ID;
+  return processEnv("AGENT_ORG_ID");
 }
 
 function markAuthContextAccess(ctx: RequestContext | undefined) {
@@ -267,7 +324,7 @@ export function hasAuthContextAccess(ctx: RequestContext | undefined): boolean {
 export function getRequestTimezone(): string | undefined {
   const store = als.getStore();
   if (store !== undefined) return store.timezone;
-  return process.env.AGENT_USER_TIMEZONE;
+  return processEnv("AGENT_USER_TIMEZONE");
 }
 
 /**

package/corpus/core/src/shared/agent-access.ts

@@ -0,0 +1,112 @@
+export const AGENT_ACCESS_PARAM = "agent_access";
+export const DEFAULT_AGENT_ACCESS_TTL_SECONDS = 2 * 60 * 60;
+
+export interface AgentAccessResourceScope {
+  resourceKind: string;
+  resourceId: string;
+}
+
+export interface AgentAccessUrlOptions {
+  origin?: string;
+  basePath?: string;
+  tokenParam?: string;
+}
+
+export interface AgentAccessApiUrlOptions extends AgentAccessUrlOptions {
+  endpoint: string;
+  resourceId: string;
+  idParam?: string;
+  token?: string | null;
+  extraParams?: Array<[string, string | number | boolean | null | undefined]>;
+}
+
+function normalizeResourcePart(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) throw new Error(`${label} is required`);
+  return trimmed;
+}
+
+export function scopedAgentAccessResourceId(
+  resourceKind: string,
+  resourceId: string,
+): string {
+  return `${normalizeResourcePart(resourceKind, "resourceKind")}:${normalizeResourcePart(resourceId, "resourceId")}`;
+}
+
+function trimSlashes(value: string): string {
+  return value.replace(/^\/+|\/+$/g, "");
+}
+
+export function normalizeAgentAccessBasePath(basePath?: string): string {
+  const trimmed = trimSlashes(basePath ?? "");
+  return trimmed ? `/${trimmed}` : "";
+}
+
+export function normalizeAgentAccessOrigin(origin?: string): string {
+  if (!origin) return "";
+  return origin.replace(/\/+$/g, "");
+}
+
+function isAbsoluteUrl(value: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+
+export function toAgentAccessUrl(
+  pathOrUrl: string,
+  options: Pick<AgentAccessUrlOptions, "origin" | "basePath"> = {},
+): string {
+  if (isAbsoluteUrl(pathOrUrl)) return pathOrUrl;
+  const path = pathOrUrl.startsWith("/") ? pathOrUrl : `/${pathOrUrl}`;
+  return `${normalizeAgentAccessOrigin(options.origin)}${normalizeAgentAccessBasePath(options.basePath)}${path}`;
+}
+
+export function appendAgentAccessParam(
+  urlOrPath: string,
+  token: string,
+  param = AGENT_ACCESS_PARAM,
+): string {
+  const hashIndex = urlOrPath.indexOf("#");
+  const base = hashIndex >= 0 ? urlOrPath.slice(0, hashIndex) : urlOrPath;
+  const hash = hashIndex >= 0 ? urlOrPath.slice(hashIndex) : "";
+  const sep = base.includes("?") ? "&" : "?";
+  return `${base}${sep}${encodeURIComponent(param)}=${encodeURIComponent(token)}${hash}`;
+}
+
+export function buildAgentAccessUrl({
+  path,
+  token,
+  origin,
+  basePath,
+  tokenParam = AGENT_ACCESS_PARAM,
+}: AgentAccessUrlOptions & {
+  path: string;
+  token: string;
+}): string {
+  return appendAgentAccessParam(
+    toAgentAccessUrl(path, { origin, basePath }),
+    token,
+    tokenParam,
+  );
+}
+
+export function buildAgentAccessApiUrl({
+  endpoint,
+  resourceId,
+  idParam = "id",
+  token,
+  tokenParam = AGENT_ACCESS_PARAM,
+  extraParams,
+  origin,
+  basePath,
+}: AgentAccessApiUrlOptions): string {
+  const params = new URLSearchParams({ [idParam]: resourceId });
+  if (token) params.set(tokenParam, token);
+  for (const [key, value] of extraParams ?? []) {
+    if (value === undefined || value === null || value === "") continue;
+    params.set(key, String(value));
+  }
+  return toAgentAccessUrl(`${endpoint}?${params.toString()}`, {
+    origin,
+    basePath,
+  });
+}

package/corpus/core/src/shared/agent-readable-resource.ts

@@ -0,0 +1,111 @@
+import {
+  AGENT_ACCESS_PARAM,
+  buildAgentAccessApiUrl,
+  buildAgentAccessUrl,
+  toAgentAccessUrl,
+  type AgentAccessUrlOptions,
+} from "./agent-access.js";
+
+export const AGENT_READABLE_RESOURCE_SCRIPT_TYPE =
+  "application/agent-native+json";
+export const AGENT_READABLE_RESOURCE_PAYLOAD_TYPE =
+  "agent-native.resource.discovery";
+
+export interface AgentReadableResourceDiscovery {
+  type: typeof AGENT_READABLE_RESOURCE_PAYLOAD_TYPE;
+  resourceType: string;
+  resourceId: string;
+  title?: string;
+  url?: string;
+  contextUrl: string;
+  expiresAt?: string;
+  instructions?: string;
+}
+
+export interface BuildAgentReadableResourceDiscoveryOptions extends AgentAccessUrlOptions {
+  resourceType: string;
+  resourceId: string;
+  title?: string | null;
+  path?: string | null;
+  contextEndpoint: string;
+  token?: string | null;
+  expiresAt?: string | null;
+  instructions?: string | null;
+}
+
+export function safeJsonForHtml(value: unknown): string {
+  return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (char) => {
+    switch (char) {
+      case "<":
+        return "\\u003c";
+      case ">":
+        return "\\u003e";
+      case "&":
+        return "\\u0026";
+      case "\u2028":
+        return "\\u2028";
+      case "\u2029":
+        return "\\u2029";
+      default:
+        return char;
+    }
+  });
+}
+
+export function buildAgentReadableResourceDiscovery({
+  resourceType,
+  resourceId,
+  title,
+  path,
+  contextEndpoint,
+  token,
+  expiresAt,
+  instructions,
+  origin,
+  basePath,
+  tokenParam = AGENT_ACCESS_PARAM,
+}: BuildAgentReadableResourceDiscoveryOptions): AgentReadableResourceDiscovery {
+  return {
+    type: AGENT_READABLE_RESOURCE_PAYLOAD_TYPE,
+    resourceType,
+    resourceId,
+    ...(title ? { title } : {}),
+    ...(path
+      ? {
+          url: token
+            ? buildAgentAccessUrl({
+                path,
+                token,
+                origin,
+                basePath,
+                tokenParam,
+              })
+            : toAgentAccessUrl(path, { origin, basePath }),
+        }
+      : {}),
+    contextUrl: buildAgentAccessApiUrl({
+      endpoint: contextEndpoint,
+      resourceId,
+      token,
+      origin,
+      basePath,
+      tokenParam,
+    }),
+    ...(expiresAt ? { expiresAt } : {}),
+    ...(instructions ? { instructions } : {}),
+  };
+}
+
+export function renderAgentReadableResourceDiscoveryScript(
+  discovery: AgentReadableResourceDiscovery,
+  options: { id?: string } = {},
+): string {
+  const id = options.id ? ` id="${escapeHtmlAttribute(options.id)}"` : "";
+  return `<script type="${AGENT_READABLE_RESOURCE_SCRIPT_TYPE}"${id}>${safeJsonForHtml(
+    discovery,
+  )}</script>`;
+}
+
+function escapeHtmlAttribute(value: string): string {
+  return value.replace(/[&"]/g, (char) => (char === "&" ? "&amp;" : "&quot;"));
+}

package/corpus/core/src/shared/index.ts

@@ -58,3 +58,26 @@ export {
   EMBED_START_PATH,
   EMBED_TOKEN_QUERY_PARAM,
 } from "./embed-auth.js";
+export {
+  AGENT_ACCESS_PARAM,
+  DEFAULT_AGENT_ACCESS_TTL_SECONDS,
+  appendAgentAccessParam,
+  buildAgentAccessApiUrl,
+  buildAgentAccessUrl,
+  normalizeAgentAccessBasePath,
+  normalizeAgentAccessOrigin,
+  scopedAgentAccessResourceId,
+  toAgentAccessUrl,
+  type AgentAccessApiUrlOptions,
+  type AgentAccessResourceScope,
+  type AgentAccessUrlOptions,
+} from "./agent-access.js";
+export {
+  AGENT_READABLE_RESOURCE_PAYLOAD_TYPE,
+  AGENT_READABLE_RESOURCE_SCRIPT_TYPE,
+  buildAgentReadableResourceDiscovery,
+  renderAgentReadableResourceDiscoveryScript,
+  safeJsonForHtml,
+  type AgentReadableResourceDiscovery,
+  type BuildAgentReadableResourceDiscoveryOptions,
+} from "./agent-readable-resource.js";