@agents24/client 0.1.0 → 0.2.1

package/dist/chunk-FNR3KPB6.js

@@ -0,0 +1,569 @@
+import { defaultClock, defaultIds, resolveEncoder, canonicalHtu, Agents24ClientError, missingCapability, normalizeBaseUrl, resolveFetch, dpopTokenRequest, absoluteUrl, encodePath, responseError, responseJson, AuthenticatedHttp } from './chunk-GXISGBVW.js';
+
+// src/base64url.ts
+function base64UrlEncode(bytes) {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let output = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index] ?? 0;
+    const second = bytes[index + 1];
+    const third = bytes[index + 2];
+    const packed = first << 16 | (second ?? 0) << 8 | (third ?? 0);
+    output += alphabet[packed >>> 18 & 63];
+    output += alphabet[packed >>> 12 & 63];
+    output += second === void 0 ? "=" : alphabet[packed >>> 6 & 63];
+    output += third === void 0 ? "=" : alphabet[packed & 63];
+  }
+  return output.replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+
+// src/dpop.ts
+function resolveCrypto(injected) {
+  const value = injected ?? globalThis.crypto;
+  if (!value?.subtle) throw missingCapability("crypto.subtle");
+  return value;
+}
+function publicJwkOnly(jwk) {
+  if (jwk.kty !== "EC" || jwk.crv !== "P-256" || !jwk.x || !jwk.y) {
+    throw new Agents24ClientError("DPoP requires a P-256 public key.", {
+      kind: "configuration",
+      code: "INVALID_DPOP_KEY"
+    });
+  }
+  return { kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y };
+}
+async function hash(subtle, encoder, input) {
+  return base64UrlEncode(new Uint8Array(await subtle.digest("SHA-256", encoder.encode(input))));
+}
+function createWebCryptoDpopKeyProvider(options = {}) {
+  const crypto = resolveCrypto(options.crypto);
+  const clock = options.clock ?? defaultClock();
+  const ids = options.ids ?? defaultIds();
+  const encoder = resolveEncoder(options.encoder);
+  let handlePromise;
+  let jwkPromise;
+  const getHandle = () => {
+    if (!handlePromise) {
+      handlePromise = (async () => {
+        const stored = await options.storage?.load();
+        if (stored) return stored;
+        const generated = await crypto.subtle.generateKey(
+          { name: "ECDSA", namedCurve: "P-256" },
+          false,
+          ["sign", "verify"]
+        );
+        await options.storage?.save(generated);
+        return generated;
+      })();
+    }
+    return handlePromise;
+  };
+  const getPublicJwk = () => {
+    if (!jwkPromise) {
+      jwkPromise = getHandle().then(async (handle) => publicJwkOnly(await crypto.subtle.exportKey("jwk", handle.publicKey)));
+    }
+    return jwkPromise;
+  };
+  return {
+    getPublicJwk,
+    async getThumbprint() {
+      const jwk = await getPublicJwk();
+      return hash(crypto.subtle, encoder, JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y }));
+    },
+    async signProof(input) {
+      const jwk = await getPublicJwk();
+      const header = base64UrlEncode(encoder.encode(JSON.stringify({ typ: "dpop+jwt", alg: "ES256", jwk })));
+      const claims = {
+        jti: ids.createId(),
+        htm: input.method.toUpperCase(),
+        htu: canonicalHtu(input.url),
+        iat: Math.floor(clock.now() / 1e3)
+      };
+      if (input.accessToken) claims.ath = await hash(crypto.subtle, encoder, input.accessToken);
+      if (input.nonce) claims.nonce = input.nonce;
+      const payload = base64UrlEncode(encoder.encode(JSON.stringify(claims)));
+      const signingInput = `${header}.${payload}`;
+      const handle = await getHandle();
+      const signature = new Uint8Array(
+        await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, handle.privateKey, encoder.encode(signingInput))
+      );
+      if (signature.byteLength !== 64) {
+        throw new Agents24ClientError("The WebCrypto provider returned a non-JOSE ECDSA signature.", {
+          kind: "configuration",
+          code: "INVALID_DPOP_SIGNATURE"
+        });
+      }
+      return `${signingInput}.${base64UrlEncode(signature)}`;
+    }
+  };
+}
+async function createPkcePair(cryptoInput, encoderInput) {
+  const crypto = resolveCrypto(cryptoInput);
+  const encoder = resolveEncoder(encoderInput);
+  const random = new Uint8Array(32);
+  const getRandomValues = crypto.getRandomValues?.bind(crypto);
+  if (!getRandomValues) throw missingCapability("crypto.getRandomValues");
+  getRandomValues(random);
+  const verifier = base64UrlEncode(random);
+  return { verifier, challenge: await hash(crypto.subtle, encoder, verifier) };
+}
+
+// src/sessions.ts
+function parseSessionToken(value, options) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Agents24ClientError("The session endpoint returned an invalid response.", {
+      kind: "protocol",
+      code: "INVALID_SESSION_RESPONSE"
+    });
+  }
+  const body = value;
+  if (typeof body.access_token !== "string" || !body.access_token || /[\r\n\0]/.test(body.access_token)) {
+    throw new Agents24ClientError("The session endpoint returned an invalid access token.", {
+      kind: "protocol",
+      code: "INVALID_SESSION_RESPONSE"
+    });
+  }
+  const tokenType = body.token_type === "DPoP" ? "DPoP" : body.token_type === "Bearer" ? "Bearer" : void 0;
+  if (!tokenType || tokenType === "DPoP" && !options.dpopKeyProvider) {
+    throw new Agents24ClientError("The session endpoint returned an unsupported token profile.", {
+      kind: "protocol",
+      code: "INVALID_TOKEN_PROFILE"
+    });
+  }
+  const parsedExpiresAt = typeof body.expires_at === "string" ? Date.parse(body.expires_at) : Number.NaN;
+  const expiresIn = typeof body.expires_in === "number" && Number.isFinite(body.expires_in) ? body.expires_in : 0;
+  const expiresAt = Number.isFinite(parsedExpiresAt) ? parsedExpiresAt : options.clock.now() + expiresIn * 1e3;
+  if (!Number.isFinite(expiresAt) || expiresAt <= options.clock.now()) {
+    throw new Agents24ClientError("The session endpoint returned an expired access token.", {
+      kind: "protocol",
+      code: "INVALID_SESSION_EXPIRY"
+    });
+  }
+  const refreshGrant = typeof body.refresh_grant === "string" && body.refresh_grant && !/[\r\n\0]/.test(body.refresh_grant) ? body.refresh_grant : void 0;
+  if (body.refresh_grant !== void 0 && !refreshGrant) {
+    throw new Agents24ClientError("The session endpoint returned an invalid refresh grant.", {
+      kind: "protocol",
+      code: "INVALID_SESSION_RESPONSE"
+    });
+  }
+  if (refreshGrant && (tokenType !== "DPoP" || !options.dpopKeyProvider)) {
+    throw new Agents24ClientError("Persistent sessions require a DPoP-bound token profile.", {
+      kind: "protocol",
+      code: "INVALID_TOKEN_PROFILE"
+    });
+  }
+  return {
+    access: {
+      accessToken: body.access_token,
+      tokenType,
+      expiresAt,
+      ...typeof body.session_id === "string" ? { sessionId: body.session_id } : {},
+      ...Array.isArray(body.capabilities) && body.capabilities.every((item) => typeof item === "string") ? { capabilities: body.capabilities } : {},
+      ...options.dpopKeyProvider ? { dpopKeyProvider: options.dpopKeyProvider } : {},
+      ...typeof body.dpop_nonce === "string" ? { dpopNonce: body.dpop_nonce } : {}
+    },
+    ...refreshGrant ? { refreshGrant } : {},
+    ...typeof (body.refresh_expires_at ?? body.refresh_grant_absolute_expires_at) === "string" ? { absoluteExpiresAt: body.refresh_expires_at ?? body.refresh_grant_absolute_expires_at } : {}
+  };
+}
+function refreshFenceLost() {
+  return new Agents24ClientError("Refresh coordination ownership changed before completion.", {
+    kind: "conflict",
+    code: "REFRESH_FENCE_LOST",
+    retryable: true
+  });
+}
+function sessionRequestAborted() {
+  return new Agents24ClientError("The session request was locally detached.", {
+    kind: "aborted",
+    code: "ABORTED",
+    retryable: false
+  });
+}
+function defaultWait(milliseconds) {
+  const schedule = globalThis.setTimeout;
+  if (!schedule) {
+    throw new Agents24ClientError("Cross-runtime refresh coordination requires a wait capability.", {
+      kind: "missing_capability",
+      code: "MISSING_WAIT_CAPABILITY"
+    });
+  }
+  return new Promise((resolve) => schedule(resolve, milliseconds));
+}
+function createFencedRefreshCoordinator(options) {
+  const clock = options.clock ?? defaultClock();
+  const ids = options.ids ?? defaultIds();
+  const ownerId = options.ownerId ?? ids.createId();
+  const leaseDurationMs = Math.max(1e3, options.leaseDurationMs ?? 6e4);
+  const pollIntervalMs = Math.max(10, options.pollIntervalMs ?? 100);
+  const wait = options.wait ?? defaultWait;
+  let local;
+  const assertActive = async (record) => {
+    const current = await options.storage.load();
+    if (!current?.active || current.fence !== record.fence || current.operationId !== record.operationId || current.ownerId !== ownerId || current.expiresAt <= clock.now()) {
+      throw refreshFenceLost();
+    }
+  };
+  const acquire = async () => {
+    while (true) {
+      const current = await options.storage.load();
+      const now = clock.now();
+      if (current?.active && current.expiresAt > now) {
+        await wait(Math.max(1, Math.min(pollIntervalMs, current.expiresAt - now)));
+        continue;
+      }
+      const next = {
+        active: true,
+        expiresAt: now + leaseDurationMs,
+        fence: (current?.fence ?? 0) + 1,
+        operationId: current?.active ? current.operationId : ids.createId(),
+        ownerId
+      };
+      if (await options.storage.compareAndSwap(current?.fence ?? null, next)) return next;
+    }
+  };
+  return {
+    async runExclusive(operation) {
+      if (local) return local;
+      const pending = (async () => {
+        const record = await acquire();
+        const lease = {
+          fence: record.fence,
+          operationId: record.operationId,
+          assertActive: () => assertActive(record)
+        };
+        try {
+          return await operation(lease);
+        } finally {
+          const current = await options.storage.load();
+          if (current?.active && current.fence === record.fence && current.operationId === record.operationId && current.ownerId === ownerId) {
+            await options.storage.compareAndSwap(current.fence, {
+              ...current,
+              active: false,
+              expiresAt: clock.now()
+            });
+          }
+        }
+      })();
+      local = pending;
+      try {
+        return await pending;
+      } finally {
+        if (local === pending) local = void 0;
+      }
+    }
+  };
+}
+function createInMemoryRefreshCoordinator() {
+  let active;
+  let fence = 0;
+  return {
+    async runExclusive(operation) {
+      if (active) return active;
+      fence += 1;
+      const ownedFence = fence;
+      const current = Promise.resolve().then(() => operation({
+        fence: ownedFence,
+        operationId: `memory-refresh-${ownedFence}`,
+        async assertActive() {
+          if (active !== current) throw refreshFenceLost();
+        }
+      }));
+      active = current;
+      try {
+        return await current;
+      } finally {
+        if (active === current) active = void 0;
+      }
+    }
+  };
+}
+function createStaticSessionProvider(access) {
+  return {
+    async getAccess() {
+      return access;
+    }
+  };
+}
+function createManagedSessionProviderInternal(options, recoverInvalidRefreshWithMint) {
+  if (options.storage && !options.dpopKeyProvider) {
+    throw new Agents24ClientError("Persistent session storage requires a DPoP key provider.", {
+      kind: "configuration",
+      code: "PERSISTENT_SESSION_REQUIRES_DPOP"
+    });
+  }
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  const fetch = resolveFetch(options.fetch);
+  const clock = options.clock ?? defaultClock();
+  const ids = options.ids ?? defaultIds();
+  const coordinator = options.coordinator ?? createInMemoryRefreshCoordinator();
+  let current;
+  let refreshGrant;
+  let minting;
+  const emit = async (event) => {
+    try {
+      await options.telemetry?.emit(event);
+    } catch {
+    }
+  };
+  const loadStored = async () => {
+    const stored = await options.storage?.load() ?? null;
+    if (!stored) return null;
+    if (!stored.refreshGrant || /[\r\n\0]/.test(stored.refreshGrant)) {
+      throw new Agents24ClientError("Stored session state is invalid.", {
+        kind: "authentication",
+        code: "INVALID_STORED_SESSION"
+      });
+    }
+    if (stored.absoluteExpiresAt) {
+      const absoluteExpiry = Date.parse(stored.absoluteExpiresAt);
+      if (!Number.isFinite(absoluteExpiry) || absoluteExpiry <= clock.now()) {
+        await options.storage?.clear();
+        throw new Agents24ClientError("The persistent session has expired.", {
+          kind: "authentication",
+          code: "SESSION_EXPIRED"
+        });
+      }
+    }
+    return stored;
+  };
+  const save = async (parsed) => {
+    current = parsed.access;
+    if (parsed.refreshGrant) refreshGrant = parsed.refreshGrant;
+    if (refreshGrant && options.storage) {
+      await options.storage.save({
+        refreshGrant,
+        ...current.sessionId ? { sessionId: current.sessionId } : {},
+        ...parsed.absoluteExpiresAt ? { absoluteExpiresAt: parsed.absoluteExpiresAt } : {}
+      });
+    }
+  };
+  const mint = async (signal) => {
+    if (signal?.aborted) throw sessionRequestAborted();
+    if (!minting) {
+      const url = absoluteUrl(baseUrl, `/public/client-runtime/deployments/${encodePath(options.deploymentId)}/sessions/anonymous`);
+      minting = options.mint({ fetch, url, dpopKeyProvider: options.dpopKeyProvider }).then(async (value) => {
+        const parsed = parseSessionToken(value, { clock, dpopKeyProvider: options.dpopKeyProvider });
+        await save(parsed);
+        return parsed.access;
+      }).finally(() => {
+        minting = void 0;
+      });
+    }
+    return minting;
+  };
+  const refresh = async (signal) => coordinator.runExclusive(async (lease) => {
+    if (signal?.aborted) throw sessionRequestAborted();
+    if (options.storage) {
+      const stored = await loadStored();
+      if (stored?.refreshGrant) refreshGrant = stored.refreshGrant;
+    }
+    if (!refreshGrant) return mint(signal);
+    await lease.assertActive();
+    const response = await dpopTokenRequest({
+      fetch,
+      url: absoluteUrl(baseUrl, "/public/client-runtime/sessions/refresh"),
+      body: { refresh_grant: refreshGrant },
+      dpopKeyProvider: options.dpopKeyProvider,
+      // Refresh grants rotate exactly once. Never abandon the credential
+      // transaction because a consuming request was locally cancelled.
+      idempotencyKey: lease.operationId
+    });
+    if (!response.ok) {
+      if (response.status === 400 || response.status === 401 || response.status === 403) {
+        await lease.assertActive();
+        await options.storage?.clear();
+        refreshGrant = void 0;
+        current = void 0;
+        if (recoverInvalidRefreshWithMint) return mint(signal);
+      }
+      throw await responseError(response);
+    }
+    await lease.assertActive();
+    const parsed = parseSessionToken(await responseJson(response), { clock, dpopKeyProvider: options.dpopKeyProvider });
+    await save(parsed);
+    await emit({ type: "session.refreshed", operation: "session" });
+    return parsed.access;
+  });
+  let provider;
+  provider = {
+    async getAccess(context) {
+      if (current && current.expiresAt > clock.now()) return current;
+      if (refreshGrant || (await loadStored())?.refreshGrant) return refresh(context.signal);
+      return mint(context.signal);
+    },
+    async refresh(context) {
+      return refresh(context.signal);
+    },
+    async revoke(input) {
+      const authenticated = new AuthenticatedHttp({
+        baseUrl,
+        sessionProvider: provider,
+        fetch,
+        clock
+      });
+      await authenticated.json("POST", "/public/client-runtime/sessions/revoke", {
+        operation: "sessions.revoke",
+        idempotencyKey: input?.idempotencyKey ?? ids.createId(),
+        ...input?.signal ? { signal: input.signal } : {}
+      });
+      current = void 0;
+      refreshGrant = void 0;
+      await options.storage?.clear();
+      await emit({ type: "session.revoked", operation: "session" });
+    }
+  };
+  return provider;
+}
+function createManagedSessionProvider(options) {
+  return createManagedSessionProviderInternal(options, false);
+}
+function createAnonymousSessionProvider(options) {
+  if ((options.persistent || options.nativeProfileId) && !options.dpopKeyProvider) {
+    throw new Agents24ClientError("Persistent and native anonymous sessions require a DPoP key provider.", {
+      kind: "configuration",
+      code: "MISSING_DPOP_PROVIDER"
+    });
+  }
+  return createManagedSessionProviderInternal(
+    {
+      ...options,
+      async mint({ fetch, url, dpopKeyProvider, signal }) {
+        const response = await dpopTokenRequest({
+          fetch,
+          url,
+          body: {
+            persistent: options.persistent ?? false,
+            requested_capabilities: [...options.requestedCapabilities ?? []],
+            ...options.nativeProfileId ? { native_profile_id: options.nativeProfileId } : {},
+            ...dpopKeyProvider ? { dpop_public_jwk: await dpopKeyProvider.getPublicJwk() } : {},
+            ...options.attestation ? { attestation: options.attestation } : {}
+          },
+          dpopKeyProvider,
+          prooflessInitialRequest: Boolean(dpopKeyProvider),
+          signal
+        });
+        if (!response.ok) throw await responseError(response);
+        return responseJson(response);
+      }
+    },
+    true
+  );
+}
+function createHostedOidcSessionProvider(options) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  const fetch = resolveFetch(options.fetch);
+  const clock = options.clock ?? defaultClock();
+  let current;
+  let refreshGrant;
+  let enrollmentNonce;
+  const ids = options.ids ?? defaultIds();
+  let memoryRecord = null;
+  const effectiveStorage = {
+    async load() {
+      return await options.storage?.load() ?? memoryRecord;
+    },
+    async save(record) {
+      memoryRecord = record;
+      await options.storage?.save(record);
+    },
+    async clear() {
+      memoryRecord = null;
+      await options.storage?.clear();
+    }
+  };
+  const baseProvider = createManagedSessionProvider({
+    ...options,
+    storage: effectiveStorage,
+    async mint() {
+      throw new Agents24ClientError("Complete the hosted OIDC authorization before requesting access.", {
+        kind: "authentication",
+        code: "OIDC_AUTHORIZATION_REQUIRED"
+      });
+    }
+  });
+  return {
+    async beginAuthorization(input) {
+      const url = absoluteUrl(
+        baseUrl,
+        `/public/client-runtime/deployments/${encodePath(options.deploymentId)}/sessions/oidc/authorize`
+      );
+      const response = await dpopTokenRequest({
+        fetch,
+        url,
+        dpopKeyProvider: options.dpopKeyProvider,
+        signal: input.signal,
+        body: {
+          redirect_uri: input.redirectUri,
+          code_challenge: input.codeChallenge,
+          code_challenge_method: "S256",
+          persistent: true,
+          dpop_public_jwk: await options.dpopKeyProvider.getPublicJwk(),
+          ...input.nativeProfileId ? { native_profile_id: input.nativeProfileId } : {}
+        }
+      });
+      if (!response.ok) throw await responseError(response);
+      const body = await responseJson(response);
+      if (typeof body.authorization_url !== "string") {
+        throw new Agents24ClientError("The OIDC endpoint returned an invalid authorization URL.", {
+          kind: "protocol",
+          code: "INVALID_OIDC_RESPONSE"
+        });
+      }
+      if (typeof body.dpop_nonce !== "string" || !body.dpop_nonce) {
+        throw new Agents24ClientError("The OIDC endpoint did not return a DPoP enrollment nonce.", {
+          kind: "protocol",
+          code: "INVALID_OIDC_RESPONSE"
+        });
+      }
+      enrollmentNonce = body.dpop_nonce;
+      return { authorizationUrl: body.authorization_url };
+    },
+    async exchange(input) {
+      const response = await dpopTokenRequest({
+        fetch,
+        url: absoluteUrl(
+          baseUrl,
+          `/public/client-runtime/deployments/${encodePath(options.deploymentId)}/sessions/oidc/exchange`
+        ),
+        dpopKeyProvider: options.dpopKeyProvider,
+        signal: input.signal,
+        idempotencyKey: ids.createId(),
+        nonce: enrollmentNonce,
+        body: { code: input.code, code_verifier: input.codeVerifier }
+      });
+      if (!response.ok) throw await responseError(response);
+      const parsed = parseSessionToken(await responseJson(response), {
+        clock,
+        dpopKeyProvider: options.dpopKeyProvider
+      });
+      current = parsed.access;
+      enrollmentNonce = void 0;
+      refreshGrant = parsed.refreshGrant;
+      if (refreshGrant) {
+        await effectiveStorage.save({
+          refreshGrant,
+          ...current.sessionId ? { sessionId: current.sessionId } : {},
+          ...parsed.absoluteExpiresAt ? { absoluteExpiresAt: parsed.absoluteExpiresAt } : {}
+        });
+      }
+      return current;
+    },
+    async getAccess(context) {
+      if (current && current.expiresAt > clock.now()) return current;
+      return baseProvider.getAccess(context);
+    },
+    async refresh(context) {
+      return baseProvider.refresh?.(context) ?? Promise.reject(new Error("Refresh unavailable"));
+    },
+    async revoke(input) {
+      await baseProvider.revoke?.(input);
+      current = void 0;
+      refreshGrant = void 0;
+    }
+  };
+}
+
+export { createAnonymousSessionProvider, createFencedRefreshCoordinator, createHostedOidcSessionProvider, createInMemoryRefreshCoordinator, createManagedSessionProvider, createPkcePair, createStaticSessionProvider, createWebCryptoDpopKeyProvider };
+//# sourceMappingURL=chunk-FNR3KPB6.js.map
+//# sourceMappingURL=chunk-FNR3KPB6.js.map