nexus-ai-pro 2.20.2 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (233) hide show
  1. package/API_STABILITY.md +93 -0
  2. package/CHANGELOG.md +208 -1
  3. package/README.md +11 -6
  4. package/SECURITY.md +16 -2
  5. package/dist/adapter-kit/gather.d.ts +76 -0
  6. package/dist/adapter-kit/gather.js +147 -0
  7. package/dist/adapter-kit/index.d.ts +1 -0
  8. package/dist/adapter-kit/index.js +1 -0
  9. package/dist/adapter-kit/record.d.ts +3 -1
  10. package/dist/adapter-kit/record.js +20 -5
  11. package/dist/agent/openapi.d.ts +94 -8
  12. package/dist/agent/openapi.js +528 -32
  13. package/dist/cli/adapters.d.ts +4 -3
  14. package/dist/cli/adapters.js +71 -2
  15. package/dist/cli/doctor.js +3 -0
  16. package/dist/cli.js +3 -1
  17. package/dist/core/config-builder.d.ts +1 -0
  18. package/dist/core/config-builder.js +1 -0
  19. package/dist/core/defaults.d.ts +34 -0
  20. package/dist/core/defaults.js +39 -0
  21. package/dist/core/secure-stream.js +4 -1
  22. package/dist/decisions/completion.d.ts +10 -7
  23. package/dist/decisions/completion.js +82 -8
  24. package/dist/decisions/core.d.ts +88 -43
  25. package/dist/decisions/core.js +115 -28
  26. package/dist/decisions/errors.d.ts +25 -0
  27. package/dist/decisions/errors.js +12 -0
  28. package/dist/decisions/index.d.ts +6 -5
  29. package/dist/decisions/index.js +2 -1
  30. package/dist/decisions/integrations.d.ts +14 -5
  31. package/dist/decisions/integrations.js +16 -1
  32. package/dist/decisions/mock.d.ts +5 -3
  33. package/dist/decisions/mock.js +4 -1
  34. package/dist/decisions/pictures.d.ts +43 -0
  35. package/dist/decisions/pictures.js +103 -0
  36. package/dist/decisions/typesafe.d.ts +33 -5
  37. package/dist/decisions/typesafe.js +121 -8
  38. package/dist/doctor/index.d.ts +6 -9
  39. package/dist/doctor/index.js +41 -0
  40. package/dist/embeddings/adapters.d.ts +1 -1
  41. package/dist/embeddings/adapters.js +3 -3
  42. package/dist/embeddings/batch-google.d.ts +27 -8
  43. package/dist/embeddings/batch-google.js +112 -36
  44. package/dist/embeddings/batch-mock.js +1 -1
  45. package/dist/embeddings/batch.js +10 -4
  46. package/dist/embeddings/engine.js +14 -13
  47. package/dist/embeddings/index.d.ts +1 -1
  48. package/dist/embeddings/inputs.d.ts +26 -3
  49. package/dist/embeddings/inputs.js +84 -5
  50. package/dist/embeddings/mock.js +1 -1
  51. package/dist/embeddings/models.js +39 -4
  52. package/dist/loaders/csv.d.ts +23 -1
  53. package/dist/loaders/csv.js +125 -72
  54. package/dist/loaders/index.d.ts +7 -2
  55. package/dist/loaders/input.d.ts +6 -0
  56. package/dist/loaders/input.js +42 -1
  57. package/dist/loaders/json.d.ts +14 -3
  58. package/dist/loaders/json.js +171 -20
  59. package/dist/loaders/web.d.ts +55 -0
  60. package/dist/loaders/web.js +20 -1
  61. package/dist/mcp/client.d.ts +54 -5
  62. package/dist/mcp/client.js +171 -20
  63. package/dist/mcp/http.d.ts +45 -0
  64. package/dist/mcp/http.js +233 -0
  65. package/dist/mcp/index.d.ts +4 -2
  66. package/dist/mcp/index.js +3 -1
  67. package/dist/mcp/protocol.d.ts +107 -0
  68. package/dist/mcp/sampling.d.ts +41 -0
  69. package/dist/mcp/sampling.js +52 -0
  70. package/dist/mcp/server.d.ts +96 -14
  71. package/dist/mcp/server.js +274 -59
  72. package/dist/models/data.js +20 -1
  73. package/dist/operations/adapters.d.ts +1 -0
  74. package/dist/operations/adapters.js +3 -1
  75. package/dist/protocols/a2a-grpc.js +10 -3
  76. package/dist/protocols/a2a-signing.d.ts +65 -0
  77. package/dist/protocols/a2a-signing.js +133 -0
  78. package/dist/protocols/a2a.d.ts +14 -0
  79. package/dist/protocols/a2a.js +60 -5
  80. package/dist/providers/cohere.js +16 -2
  81. package/dist/providers/google.js +7 -1
  82. package/dist/providers/ollama.d.ts +1 -1
  83. package/dist/providers/ollama.js +35 -27
  84. package/dist/providers/openai.js +19 -2
  85. package/dist/rag/pinecone.d.ts +63 -2
  86. package/dist/rag/pinecone.js +80 -0
  87. package/dist/realtime/conversation.js +18 -0
  88. package/dist/realtime/gemini-live.transport.d.ts +28 -3
  89. package/dist/realtime/gemini-live.transport.js +170 -32
  90. package/dist/realtime/session.d.ts +2 -0
  91. package/dist/realtime/session.js +19 -4
  92. package/dist/realtime/types.d.ts +35 -3
  93. package/dist/security/output-guard.js +4 -1
  94. package/dist/server/auth.d.ts +263 -2
  95. package/dist/server/auth.js +432 -5
  96. package/dist/server/deployments.d.ts +3 -2
  97. package/dist/server/deployments.js +6 -1
  98. package/dist/telephony/index.d.ts +1 -1
  99. package/dist/telephony/manager.d.ts +8 -1
  100. package/dist/telephony/manager.js +13 -0
  101. package/dist/telephony/providers/telnyx.d.ts +18 -5
  102. package/dist/telephony/providers/telnyx.js +44 -7
  103. package/dist/telephony/providers/twilio.d.ts +3 -1
  104. package/dist/telephony/providers/twilio.js +16 -0
  105. package/dist/tracing/stores.d.ts +2 -0
  106. package/dist/tracing/stores.js +1 -0
  107. package/dist/tracing/tracer.d.ts +5 -2
  108. package/dist/tracing/tracer.js +6 -3
  109. package/dist/types/embeddings.d.ts +47 -5
  110. package/dist/types/messages.d.ts +7 -0
  111. package/dist/types/principal.d.ts +1 -1
  112. package/dist/types/response.d.ts +5 -0
  113. package/dist/types/telephony.d.ts +38 -0
  114. package/dist/types/tracing.d.ts +6 -0
  115. package/dist/version.d.ts +1 -1
  116. package/dist/version.js +1 -1
  117. package/dist/voice/providers/google.d.ts +44 -0
  118. package/dist/voice/providers/google.js +215 -0
  119. package/dist-cjs/adapter-kit/gather.d.ts +76 -0
  120. package/dist-cjs/adapter-kit/gather.js +152 -0
  121. package/dist-cjs/adapter-kit/index.d.ts +1 -0
  122. package/dist-cjs/adapter-kit/index.js +4 -1
  123. package/dist-cjs/adapter-kit/record.d.ts +3 -1
  124. package/dist-cjs/adapter-kit/record.js +20 -5
  125. package/dist-cjs/agent/openapi.d.ts +94 -8
  126. package/dist-cjs/agent/openapi.js +530 -32
  127. package/dist-cjs/cli/adapters.d.ts +4 -3
  128. package/dist-cjs/cli/adapters.js +70 -1
  129. package/dist-cjs/cli/doctor.js +3 -0
  130. package/dist-cjs/core/config-builder.d.ts +1 -0
  131. package/dist-cjs/core/config-builder.js +5 -1
  132. package/dist-cjs/core/defaults.d.ts +34 -0
  133. package/dist-cjs/core/defaults.js +44 -0
  134. package/dist-cjs/core/secure-stream.js +4 -1
  135. package/dist-cjs/decisions/completion.d.ts +10 -7
  136. package/dist-cjs/decisions/completion.js +81 -7
  137. package/dist-cjs/decisions/core.d.ts +88 -43
  138. package/dist-cjs/decisions/core.js +134 -46
  139. package/dist-cjs/decisions/errors.d.ts +25 -0
  140. package/dist-cjs/decisions/errors.js +16 -0
  141. package/dist-cjs/decisions/index.d.ts +6 -5
  142. package/dist-cjs/decisions/index.js +5 -1
  143. package/dist-cjs/decisions/integrations.d.ts +14 -5
  144. package/dist-cjs/decisions/integrations.js +16 -1
  145. package/dist-cjs/decisions/mock.d.ts +5 -3
  146. package/dist-cjs/decisions/mock.js +4 -1
  147. package/dist-cjs/decisions/pictures.d.ts +43 -0
  148. package/dist-cjs/decisions/pictures.js +109 -0
  149. package/dist-cjs/decisions/typesafe.d.ts +33 -5
  150. package/dist-cjs/decisions/typesafe.js +126 -13
  151. package/dist-cjs/doctor/index.d.ts +6 -9
  152. package/dist-cjs/doctor/index.js +41 -0
  153. package/dist-cjs/embeddings/adapters.d.ts +1 -1
  154. package/dist-cjs/embeddings/adapters.js +3 -3
  155. package/dist-cjs/embeddings/batch-google.d.ts +27 -8
  156. package/dist-cjs/embeddings/batch-google.js +112 -36
  157. package/dist-cjs/embeddings/batch-mock.js +1 -1
  158. package/dist-cjs/embeddings/batch.js +9 -3
  159. package/dist-cjs/embeddings/engine.js +13 -12
  160. package/dist-cjs/embeddings/index.d.ts +1 -1
  161. package/dist-cjs/embeddings/inputs.d.ts +26 -3
  162. package/dist-cjs/embeddings/inputs.js +89 -5
  163. package/dist-cjs/embeddings/mock.js +1 -1
  164. package/dist-cjs/embeddings/models.js +39 -4
  165. package/dist-cjs/loaders/csv.d.ts +23 -1
  166. package/dist-cjs/loaders/csv.js +126 -71
  167. package/dist-cjs/loaders/index.d.ts +7 -2
  168. package/dist-cjs/loaders/input.d.ts +6 -0
  169. package/dist-cjs/loaders/input.js +43 -1
  170. package/dist-cjs/loaders/json.d.ts +14 -3
  171. package/dist-cjs/loaders/json.js +170 -19
  172. package/dist-cjs/loaders/web.d.ts +55 -0
  173. package/dist-cjs/loaders/web.js +21 -1
  174. package/dist-cjs/mcp/client.d.ts +54 -5
  175. package/dist-cjs/mcp/client.js +171 -20
  176. package/dist-cjs/mcp/http.d.ts +45 -0
  177. package/dist-cjs/mcp/http.js +236 -0
  178. package/dist-cjs/mcp/index.d.ts +4 -2
  179. package/dist-cjs/mcp/index.js +5 -1
  180. package/dist-cjs/mcp/protocol.d.ts +107 -0
  181. package/dist-cjs/mcp/sampling.d.ts +41 -0
  182. package/dist-cjs/mcp/sampling.js +55 -0
  183. package/dist-cjs/mcp/server.d.ts +96 -14
  184. package/dist-cjs/mcp/server.js +273 -58
  185. package/dist-cjs/models/data.js +20 -1
  186. package/dist-cjs/operations/adapters.d.ts +1 -0
  187. package/dist-cjs/operations/adapters.js +3 -1
  188. package/dist-cjs/protocols/a2a-grpc.js +10 -3
  189. package/dist-cjs/protocols/a2a-signing.d.ts +65 -0
  190. package/dist-cjs/protocols/a2a-signing.js +140 -0
  191. package/dist-cjs/protocols/a2a.d.ts +14 -0
  192. package/dist-cjs/protocols/a2a.js +65 -6
  193. package/dist-cjs/providers/cohere.js +16 -2
  194. package/dist-cjs/providers/google.js +7 -1
  195. package/dist-cjs/providers/ollama.d.ts +1 -1
  196. package/dist-cjs/providers/ollama.js +35 -27
  197. package/dist-cjs/providers/openai.js +19 -2
  198. package/dist-cjs/rag/pinecone.d.ts +63 -2
  199. package/dist-cjs/rag/pinecone.js +81 -0
  200. package/dist-cjs/realtime/conversation.js +18 -0
  201. package/dist-cjs/realtime/gemini-live.transport.d.ts +28 -3
  202. package/dist-cjs/realtime/gemini-live.transport.js +170 -32
  203. package/dist-cjs/realtime/session.d.ts +2 -0
  204. package/dist-cjs/realtime/session.js +19 -4
  205. package/dist-cjs/realtime/types.d.ts +35 -3
  206. package/dist-cjs/security/output-guard.js +4 -1
  207. package/dist-cjs/server/auth.d.ts +263 -2
  208. package/dist-cjs/server/auth.js +437 -5
  209. package/dist-cjs/server/deployments.d.ts +3 -2
  210. package/dist-cjs/server/deployments.js +6 -1
  211. package/dist-cjs/telephony/index.d.ts +1 -1
  212. package/dist-cjs/telephony/manager.d.ts +8 -1
  213. package/dist-cjs/telephony/manager.js +13 -0
  214. package/dist-cjs/telephony/providers/telnyx.d.ts +18 -5
  215. package/dist-cjs/telephony/providers/telnyx.js +44 -7
  216. package/dist-cjs/telephony/providers/twilio.d.ts +3 -1
  217. package/dist-cjs/telephony/providers/twilio.js +16 -0
  218. package/dist-cjs/tracing/stores.d.ts +2 -0
  219. package/dist-cjs/tracing/stores.js +1 -0
  220. package/dist-cjs/tracing/tracer.d.ts +5 -2
  221. package/dist-cjs/tracing/tracer.js +6 -3
  222. package/dist-cjs/types/embeddings.d.ts +47 -5
  223. package/dist-cjs/types/messages.d.ts +7 -0
  224. package/dist-cjs/types/principal.d.ts +1 -1
  225. package/dist-cjs/types/response.d.ts +5 -0
  226. package/dist-cjs/types/telephony.d.ts +38 -0
  227. package/dist-cjs/types/tracing.d.ts +6 -0
  228. package/dist-cjs/version.d.ts +1 -1
  229. package/dist-cjs/version.js +1 -1
  230. package/dist-cjs/voice/providers/google.d.ts +44 -0
  231. package/dist-cjs/voice/providers/google.js +252 -0
  232. package/llms.txt +1 -1
  233. package/package.json +17 -1
@@ -1,13 +1,16 @@
1
1
  /**
2
- * Authentication for the agent server: JSON Web Tokens, API keys, and a trusted proxy.
2
+ * Authentication for the agent server: JSON Web Tokens, API keys, sessions, and a trusted proxy.
3
3
  *
4
4
  * Each builds the `authenticate` hook of `createAgentServer()`, and each returns the same
5
5
  * `Principal`: a subject, a tenant, roles, and scopes. That principal is what scopes threads, runs,
6
6
  * budgets, and the store to a tenant, and what reaches every graph node, tool, and middleware of the
7
- * run. Everything is built on Web Crypto, so there is no dependency and it runs wherever `fetch` does.
7
+ * run. The application issues its own tokens with `createJwtSigner()`, keeps its own keys with
8
+ * `createApiKeyStore()`, and signs browsers in with `createSessions()`. Everything is built on Web
9
+ * Crypto, so there is no dependency and it runs wherever `fetch` does.
8
10
  */
9
11
  import type { webcrypto } from 'node:crypto';
10
12
  import type { Principal } from '../types/principal.js';
13
+ import type { ServerStateStore } from '../types/server.js';
11
14
  type JsonWebKey = webcrypto.JsonWebKey;
12
15
  type CryptoKey = webcrypto.CryptoKey;
13
16
  /** The `authenticate` hook of `createAgentServer()`. */
@@ -237,6 +240,264 @@ export interface TrustedProxyAuthOptions {
237
240
  * `method: 'proxy'`.
238
241
  */
239
242
  export declare function trustedProxyAuth(options: TrustedProxyAuthOptions): AuthHook;
243
+ /** Options for `createJwtSigner()`. Give it one key: `secret`, `privateKey`, or `keyPair`. */
244
+ export interface JwtSignerOptions {
245
+ /** A shared secret, for HS256, HS384, and HS512, which `jwtAuth({ secret })` verifies with. At least 32 bytes. */
246
+ secret?: string | Uint8Array;
247
+ /** A private key: PEM (`-----BEGIN PRIVATE KEY-----`, PKCS #8), or a private JWK, as `generateJwtKey()` makes one. */
248
+ privateKey?: string | JsonWebKey;
249
+ /** A Web Crypto key pair, as `crypto.subtle.generateKey()` makes one, its public key extractable. */
250
+ keyPair?: {
251
+ privateKey: CryptoKey;
252
+ publicKey: CryptoKey;
253
+ };
254
+ /**
255
+ * The algorithm. Defaults to HS256 for a secret, and to the key's own for a JWK or a key pair: its
256
+ * `alg`, or RS256 for RSA, ES256, ES384, or ES512 by curve, and EdDSA for Ed25519. A PEM key names it.
257
+ */
258
+ algorithm?: JwtAlgorithm;
259
+ /** The key's id, in each token's header and the key set. Defaults to the public key's RFC 7638 thumbprint; a secret has none. */
260
+ kid?: string;
261
+ /** The issuer every token names. */
262
+ issuer?: string;
263
+ /** The audience every token is for, unless one is issued for another. */
264
+ audience?: string | readonly string[];
265
+ /** How long a token lasts, in seconds, unless one is issued for longer or shorter. Defaults to an hour. */
266
+ expiresInSec?: number;
267
+ /** Replaces the clock, in milliseconds since the epoch, for tests. */
268
+ now?: () => number;
269
+ }
270
+ /** What one token is issued with, over the signer's own. */
271
+ export interface JwtSignOptions {
272
+ /** How long it lasts, in seconds. */
273
+ expiresInSec?: number;
274
+ /** Who it is for. */
275
+ audience?: string | readonly string[];
276
+ /** Seconds from now before which it is not valid. */
277
+ notBeforeSec?: number;
278
+ }
279
+ /** Issues tokens with one key, which `jwtAuth()`, `createJwtVerifier()`, and any other verifier read. */
280
+ export interface JwtSigner {
281
+ /** The algorithm it signs with. */
282
+ readonly algorithm: JwtAlgorithm;
283
+ /**
284
+ * Signs claims into a token: the signer's issuer and audience, `iat`, `exp`, and a `jti` of its own,
285
+ * then the claims given, which win.
286
+ */
287
+ sign(claims?: JwtPayload, options?: JwtSignOptions): Promise<string>;
288
+ /**
289
+ * A token for a principal: its user as `sub`, its tenant, roles, and scopes, under the claim names
290
+ * `jwtAuth()` reads them from, so the same `claims` names read it back.
291
+ */
292
+ issue(principal: Principal, options?: JwtSignOptions & {
293
+ claims?: JwtClaimNames;
294
+ }): Promise<string>;
295
+ /** The public key, as a JWK with its `kid`, `alg`, and `use`, for a key set; none for a secret. */
296
+ publicKey(): Promise<JsonWebKey | undefined>;
297
+ }
298
+ /**
299
+ * Builds a signer, to issue tokens of your own: for a service, after a sign-in, or for a test.
300
+ *
301
+ * ```ts
302
+ * const signer = createJwtSigner({ privateKey: JSON.parse(process.env.JWT_KEY ?? ''), issuer: 'https://agents.example.com' });
303
+ * const token = await signer.issue({ userId: 'ana', tenantId: 'acme', scopes: ['read'] }, { audience: 'agents-api' });
304
+ * ```
305
+ */
306
+ export declare function createJwtSigner(options: JwtSignerOptions): JwtSigner;
307
+ /**
308
+ * A new private key for `createJwtSigner()`, as a JWK with its `kid`, `alg`, and `use`: keep it in a
309
+ * secret store, and the signer publishes its public half. Defaults to ES256.
310
+ */
311
+ export declare function generateJwtKey(algorithm?: Exclude<JwtAlgorithm, 'HS256' | 'HS384' | 'HS512'>): Promise<JsonWebKey & {
312
+ kid: string;
313
+ alg: string;
314
+ }>;
315
+ /**
316
+ * Serves signers' public keys as a JSON Web Key Set, at the URL `jwtAuth({ jwks })` and other services
317
+ * read. Give it the signer in use and those whose tokens may still be live, so a key rotation never
318
+ * refuses a token signed before it.
319
+ *
320
+ * ```ts
321
+ * if (new URL(request.url).pathname === '/.well-known/jwks.json') return jwks(request);
322
+ * ```
323
+ */
324
+ export declare function jwksHandler(...signers: JwtSigner[]): (request: Request) => Promise<Response>;
325
+ /** An API key as it is kept: its hash, never the key, with the principal it stands for. */
326
+ export interface ApiKeyRecord {
327
+ /** Its id, which names it in a list and to `revoke()` and `rotate()`. Not a secret. */
328
+ id: string;
329
+ /** The key's SHA-256, as `hashApiKey()` gives it. */
330
+ hash: string;
331
+ /** The key's first characters, its prefix and four more, to recognise it by. */
332
+ start: string;
333
+ /** Who the key stands for. */
334
+ principal: Principal;
335
+ /** What it is for, in words. */
336
+ label?: string;
337
+ /** When it was issued, in milliseconds since the epoch. */
338
+ createdAt: number;
339
+ /** When it stops working, in milliseconds since the epoch. */
340
+ expiresAt?: number;
341
+ /** When it was last used, to the store's `touchEveryMs`. */
342
+ lastUsedAt?: number;
343
+ /** When it was revoked. */
344
+ revokedAt?: number;
345
+ /** The id of the key that replaced it, when it was rotated. */
346
+ replacedBy?: string;
347
+ }
348
+ /** A key just issued: the key itself, shown this once, and its record. */
349
+ export interface IssuedApiKey {
350
+ /** The key, to hand to whoever will use it. It is never stored, so it cannot be shown again. */
351
+ key: string;
352
+ /** Its record. */
353
+ record: ApiKeyRecord;
354
+ }
355
+ /** What a key is issued with. */
356
+ export interface ApiKeyIssueOptions {
357
+ /** What it is for, in words. */
358
+ label?: string;
359
+ /** How long it works, in seconds. Without it, until it is revoked. */
360
+ expiresInSec?: number;
361
+ }
362
+ /** Options for `createApiKeyStore()`. */
363
+ export interface ApiKeyStoreOptions {
364
+ /**
365
+ * Where keys are kept: the server's state store, so every replica reads the same keys. Defaults to
366
+ * a `MemoryServerStore`, which one process alone reads.
367
+ */
368
+ store?: ServerStateStore;
369
+ /** What every key begins with, so it is recognised in a log or by a secret scanner. Defaults to `nxk_`. */
370
+ prefix?: string;
371
+ /** The least time between two writes of a key's `lastUsedAt`, in milliseconds. Defaults to a minute. */
372
+ touchEveryMs?: number;
373
+ /** Replaces the clock, in milliseconds since the epoch, for tests. */
374
+ now?: () => number;
375
+ }
376
+ /** API keys issued, rotated, and revoked by the application, which `apiKeyAuth()` reads by their hash. */
377
+ export interface ApiKeyStore {
378
+ /** Issues a key for a principal. */
379
+ issue(principal: Principal, options?: ApiKeyIssueOptions): Promise<IssuedApiKey>;
380
+ /**
381
+ * Replaces a key with a new one for the same principal and label. The old one works for `graceSec`
382
+ * more, 0 by default, so what uses it can move to the new one first.
383
+ */
384
+ rotate(id: string, options?: ApiKeyIssueOptions & {
385
+ graceSec?: number;
386
+ }): Promise<IssuedApiKey>;
387
+ /** Revokes a key at once. Resolves whether there was one to revoke. */
388
+ revoke(id: string): Promise<boolean>;
389
+ /** A key's record. */
390
+ get(id: string): Promise<ApiKeyRecord | undefined>;
391
+ /** Records, newest first, a tenant's alone when `tenantId` is given; `limit` read, 1,000 by default. */
392
+ list(options?: {
393
+ tenantId?: string;
394
+ limit?: number;
395
+ }): Promise<ApiKeyRecord[]>;
396
+ /** The principal a key stands for, by its hash, while it works: `apiKeyAuth({ lookup })`. */
397
+ lookup(hash: string): Promise<Principal | undefined>;
398
+ /** `apiKeyAuth()` over this store, taking only keys with its prefix. */
399
+ auth(options?: Pick<ApiKeyAuthOptions, 'header'>): AuthHook;
400
+ }
401
+ /**
402
+ * API keys the application issues and revokes itself, kept as hashes in the server's state store.
403
+ *
404
+ * ```ts
405
+ * const keys = createApiKeyStore({ store: fromStore(redisStore) });
406
+ * const { key } = await keys.issue({ userId: 'ci', tenantId: 'acme', scopes: ['write'] }, { label: 'CI' });
407
+ * createAgentServer({ assistants, state: fromStore(redisStore), authenticate: anyAuth(jwtAuth({ ... }), keys.auth()) });
408
+ * ```
409
+ */
410
+ export declare function createApiKeyStore(options?: ApiKeyStoreOptions): ApiKeyStore;
411
+ /** How the session cookie is written. */
412
+ export interface SessionCookieOptions {
413
+ /** Its name. Defaults to `__Host-nexus_session`, which a browser binds to this host alone, or `nexus_session` where that cannot be used. */
414
+ name?: string;
415
+ /** The domain it is sent to, besides this host. Defaults to none: this host alone. */
416
+ domain?: string;
417
+ /** The path it is sent for. Defaults to `/`. */
418
+ path?: string;
419
+ /** Sent over HTTPS alone. Defaults to true; false for plain HTTP on a developer's machine. */
420
+ secure?: boolean;
421
+ /** Whether a browser sends it from another site. Defaults to `Lax`; `None` needs `secure`. */
422
+ sameSite?: 'Strict' | 'Lax' | 'None';
423
+ }
424
+ /** Options for `createSessions()`. */
425
+ export interface SessionOptions {
426
+ /** Where sessions are kept: the server's state store, so every replica reads them. Defaults to a `MemoryServerStore`. */
427
+ store?: ServerStateStore;
428
+ /** How the cookie is written. */
429
+ cookie?: SessionCookieOptions;
430
+ /** The longest a session lasts from its start, in seconds. Defaults to 8 hours. */
431
+ maxAgeSec?: number;
432
+ /** How long a session lasts unused, in seconds. Defaults to the longest it lasts. */
433
+ idleSec?: number;
434
+ /**
435
+ * Origins a request that changes something may come from, besides the request URL's own: the
436
+ * application's public origin, when a proxy in front makes the server see another.
437
+ */
438
+ origins?: readonly string[];
439
+ /** Replaces the clock, in milliseconds since the epoch, for tests. */
440
+ now?: () => number;
441
+ }
442
+ /** A session as it is kept: the hash of its secret, never the secret, with whom it is for. */
443
+ export interface SessionRecord {
444
+ /** Its id, which names it to `revoke()`. Not a secret. */
445
+ id: string;
446
+ /** The SHA-256 of the secret the cookie carries. */
447
+ hash: string;
448
+ /** Who signed in. */
449
+ principal: Principal;
450
+ /** When it started, in milliseconds since the epoch. */
451
+ createdAt: number;
452
+ /** When it ends, however much it is used. */
453
+ expiresAt: number;
454
+ /** When it was last used, to the minute. */
455
+ lastSeenAt?: number;
456
+ }
457
+ /** A session just started. */
458
+ export interface StartedSession {
459
+ /** The value of a `Set-Cookie` header, for the response to the sign-in. */
460
+ cookie: string;
461
+ /** Its record. */
462
+ record: SessionRecord;
463
+ }
464
+ /** Browser sessions: a cookie after a sign-in of the application's own, and the hook that reads it. */
465
+ export interface Sessions {
466
+ /** Starts a session for a principal: set the cookie it returns on the sign-in's response. */
467
+ start(principal: Principal): Promise<StartedSession>;
468
+ /** Ends the request's session, and returns the `Set-Cookie` value that clears its cookie. */
469
+ end(request: Request): Promise<string>;
470
+ /** Ends a session by its id, wherever its cookie is. Resolves whether there was one. */
471
+ revoke(id: string): Promise<boolean>;
472
+ /** Live sessions, newest first, a user's or a tenant's alone when one is given; `limit` read, 1,000 by default. */
473
+ list(options?: {
474
+ userId?: string;
475
+ tenantId?: string;
476
+ limit?: number;
477
+ }): Promise<SessionRecord[]>;
478
+ /** Removes sessions that have ended, up to 10,000 at a time, and resolves how many. Call it now and then, from a cron job. */
479
+ sweep(): Promise<number>;
480
+ /**
481
+ * The `authenticate` hook. A request with no cookie is passed over; an ended or forged one answers
482
+ * 401 and clears the cookie; a request that changes something, from a page of another origin,
483
+ * answers 403. The principal carries `method: 'session'` and its id as the `sid` claim.
484
+ */
485
+ readonly auth: AuthHook;
486
+ }
487
+ /**
488
+ * Browser sessions after a sign-in of the application's own: a password, a magic link, or an identity
489
+ * provider's redirect. The cookie carries a random secret, the store its hash, so a copy of the store
490
+ * signs no one in; it is `HttpOnly`, `Secure`, and `SameSite=Lax` by default, and a request that
491
+ * changes something must come from the application's own origin.
492
+ *
493
+ * ```ts
494
+ * const sessions = createSessions({ store: fromStore(redisStore), origins: ['https://agents.example.com'] });
495
+ * // In the sign-in route, once the user is known:
496
+ * const { cookie } = await sessions.start({ userId: user.id, tenantId: user.orgId, scopes: ['read', 'write'] });
497
+ * return new Response(null, { status: 303, headers: { location: '/', 'set-cookie': cookie } });
498
+ * ```
499
+ */
500
+ export declare function createSessions(options?: SessionOptions): Sessions;
240
501
  /**
241
502
  * Tries hooks in order and takes the first principal: tokens for people and keys for services on
242
503
  * one server. When none accepts the request, the first refusal any of them gave is the answer, so a