@btps/sdk 0.0.0-stage → 1.1.1

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 (155) hide show
  1. package/CHANGELOG.md +171 -0
  2. package/LICENSE +190 -0
  3. package/NOTICE +25 -0
  4. package/README.md +261 -2
  5. package/dist/client/btpsAgent.d.ts +20 -0
  6. package/dist/client/btpsAgent.js +172 -0
  7. package/dist/client/btpsClient.d.ts +202 -0
  8. package/dist/client/btpsClient.js +602 -0
  9. package/dist/client/btpsTransporter.d.ts +52 -0
  10. package/dist/client/btpsTransporter.js +249 -0
  11. package/dist/client/constants/index.d.ts +11 -0
  12. package/dist/client/constants/index.js +20 -0
  13. package/dist/client/index.d.ts +12 -0
  14. package/dist/client/index.js +27 -0
  15. package/dist/client/libs/schema.js +56 -0
  16. package/dist/client/libs/timeouts.d.ts +22 -0
  17. package/dist/client/libs/timeouts.js +19 -0
  18. package/dist/client/types/index.d.ts +155 -0
  19. package/dist/client/types/index.js +7 -0
  20. package/dist/core/authentication/BtpsAuthentication.d.ts +128 -0
  21. package/dist/core/authentication/BtpsAuthentication.js +293 -0
  22. package/dist/core/authentication/index.d.ts +11 -0
  23. package/dist/core/authentication/index.js +12 -0
  24. package/dist/core/authentication/keyProof.d.ts +18 -0
  25. package/dist/core/authentication/keyProof.js +16 -0
  26. package/dist/core/authentication/storage/InMemoryAuthSessionStore.d.ts +55 -0
  27. package/dist/core/authentication/storage/InMemoryAuthSessionStore.js +62 -0
  28. package/dist/core/authentication/storage/InMemoryTokenStore.d.ts +63 -0
  29. package/dist/core/authentication/storage/InMemoryTokenStore.js +63 -0
  30. package/dist/core/authentication/types.d.ts +135 -0
  31. package/dist/core/authentication/types.js +7 -0
  32. package/dist/core/crypto/decryptVerify.d.ts +9 -0
  33. package/dist/core/crypto/decryptVerify.js +45 -0
  34. package/dist/core/crypto/decrypter-interface.d.ts +25 -0
  35. package/dist/core/crypto/decrypter-interface.js +7 -0
  36. package/dist/core/crypto/index.d.ts +77 -0
  37. package/dist/core/crypto/index.js +210 -0
  38. package/dist/core/crypto/jcs.d.ts +28 -0
  39. package/dist/core/crypto/jcs.js +60 -0
  40. package/dist/core/crypto/keygen.d.ts +9 -0
  41. package/dist/core/crypto/keygen.js +35 -0
  42. package/dist/core/crypto/pem-decrypter.d.ts +26 -0
  43. package/dist/core/crypto/pem-decrypter.js +52 -0
  44. package/dist/core/crypto/pem-signer.d.ts +21 -0
  45. package/dist/core/crypto/pem-signer.js +34 -0
  46. package/dist/core/crypto/signEncrypt.d.ts +34 -0
  47. package/dist/core/crypto/signEncrypt.js +75 -0
  48. package/dist/core/crypto/signer-interface.d.ts +22 -0
  49. package/dist/core/crypto/signer-interface.js +7 -0
  50. package/dist/core/crypto/types.d.ts +79 -0
  51. package/dist/core/crypto/types.js +7 -0
  52. package/dist/core/delegation/BtpsDelegator.d.ts +102 -0
  53. package/dist/core/delegation/BtpsDelegator.js +118 -0
  54. package/dist/core/delegation/index.d.ts +7 -0
  55. package/dist/core/delegation/index.js +8 -0
  56. package/dist/core/error/constant.d.ts +66 -0
  57. package/dist/core/error/constant.js +194 -0
  58. package/dist/core/error/index.d.ts +35 -0
  59. package/dist/core/error/index.js +52 -0
  60. package/dist/core/error/types.d.ts +16 -0
  61. package/dist/core/error/types.js +7 -0
  62. package/dist/core/server/constants/btps-protocol.d.ts +17 -0
  63. package/dist/core/server/constants/btps-protocol.js +25 -0
  64. package/dist/core/server/constants/control.d.ts +7 -0
  65. package/dist/core/server/constants/control.js +11 -0
  66. package/dist/core/server/constants/currency.d.ts +7 -0
  67. package/dist/core/server/constants/currency.js +332 -0
  68. package/dist/core/server/constants/index.d.ts +26 -0
  69. package/dist/core/server/constants/index.js +61 -0
  70. package/dist/core/server/constants/limits.d.ts +50 -0
  71. package/dist/core/server/constants/limits.js +50 -0
  72. package/dist/core/server/helpers/BtpsMessageQueue.d.ts +13 -0
  73. package/dist/core/server/helpers/BtpsMessageQueue.js +12 -0
  74. package/dist/core/server/helpers/InMemoryQueue.d.ts +16 -0
  75. package/dist/core/server/helpers/InMemoryQueue.js +35 -0
  76. package/dist/core/server/helpers/index.d.ts +8 -0
  77. package/dist/core/server/helpers/index.js +9 -0
  78. package/dist/core/server/schemas/artifacts/agentSchema.js +51 -0
  79. package/dist/core/server/schemas/artifacts/artifacts.js +21 -0
  80. package/dist/core/server/schemas/artifacts/controlSchema.js +18 -0
  81. package/dist/core/server/schemas/artifacts/identityLookupSchema.js +21 -0
  82. package/dist/core/server/schemas/artifacts/transporterSchema.js +60 -0
  83. package/dist/core/server/schemas/btpsDocsSchema.d.ts +4519 -0
  84. package/dist/core/server/schemas/btpsDocsSchema.js +272 -0
  85. package/dist/core/server/schemas/helpers.js +87 -0
  86. package/dist/core/server/schemas/responseSchema.js +86 -0
  87. package/dist/core/server/schemas/schema.js +70 -0
  88. package/dist/core/server/schemas/shared.js +18 -0
  89. package/dist/core/server/types.d.ts +172 -0
  90. package/dist/core/server/types.js +7 -0
  91. package/dist/core/storage/AbstractIdentityStore.d.ts +17 -0
  92. package/dist/core/storage/AbstractIdentityStore.js +13 -0
  93. package/dist/core/storage/AbstractStorageStore.d.ts +16 -0
  94. package/dist/core/storage/AbstractStorageStore.js +17 -0
  95. package/dist/core/storage/JsonIdentityStore.d.ts +29 -0
  96. package/dist/core/storage/JsonIdentityStore.js +39 -0
  97. package/dist/core/storage/JsonStorageStore.d.ts +59 -0
  98. package/dist/core/storage/JsonStorageStore.js +110 -0
  99. package/dist/core/storage/index.d.ts +11 -0
  100. package/dist/core/storage/index.js +18 -0
  101. package/dist/core/storage/types.d.ts +28 -0
  102. package/dist/core/storage/types.js +7 -0
  103. package/dist/core/trust/index.d.ts +10 -0
  104. package/dist/core/trust/index.js +15 -0
  105. package/dist/core/trust/storage/AbstractTrustStore.d.ts +23 -0
  106. package/dist/core/trust/storage/AbstractTrustStore.js +13 -0
  107. package/dist/core/trust/storage/JsonTrustStore.d.ts +33 -0
  108. package/dist/core/trust/storage/JsonTrustStore.js +42 -0
  109. package/dist/core/trust/trustUtils.d.ts +78 -0
  110. package/dist/core/trust/trustUtils.js +41 -0
  111. package/dist/core/trust/types.d.ts +53 -0
  112. package/dist/core/trust/types.js +7 -0
  113. package/dist/core/utils/identity.d.ts +20 -0
  114. package/dist/core/utils/identity.js +22 -0
  115. package/dist/core/utils/index.d.ts +70 -0
  116. package/dist/core/utils/index.js +124 -0
  117. package/dist/core/utils/types.d.ts +10 -0
  118. package/dist/core/utils/types.js +7 -0
  119. package/dist/core/utils/validation.js +13 -0
  120. package/dist/index.d.ts +7 -0
  121. package/dist/index.js +8 -0
  122. package/dist/server/btpsServer.d.ts +292 -0
  123. package/dist/server/btpsServer.js +827 -0
  124. package/dist/server/index.d.ts +11 -0
  125. package/dist/server/index.js +15 -0
  126. package/dist/server/libs/abstractRateLimiter.d.ts +10 -0
  127. package/dist/server/libs/abstractRateLimiter.js +15 -0
  128. package/dist/server/libs/artifactSizeGuard.d.ts +27 -0
  129. package/dist/server/libs/artifactSizeGuard.js +44 -0
  130. package/dist/server/libs/artifactTimeWindow.d.ts +24 -0
  131. package/dist/server/libs/artifactTimeWindow.js +30 -0
  132. package/dist/server/libs/btpsFactory.d.ts +29 -0
  133. package/dist/server/libs/btpsFactory.js +49 -0
  134. package/dist/server/libs/btpsLightweightFactory.d.ts +35 -0
  135. package/dist/server/libs/btpsLightweightFactory.js +37 -0
  136. package/dist/server/libs/btpsRegistry.d.ts +14 -0
  137. package/dist/server/libs/btpsRegistry.js +16 -0
  138. package/dist/server/libs/btpsSimpleMetricsTracker.d.ts +13 -0
  139. package/dist/server/libs/btpsSimpleMetricsTracker.js +21 -0
  140. package/dist/server/libs/btpsSimpleRateLimiter.d.ts +28 -0
  141. package/dist/server/libs/btpsSimpleRateLimiter.js +46 -0
  142. package/dist/server/libs/connectionTimeout.d.ts +16 -0
  143. package/dist/server/libs/connectionTimeout.js +14 -0
  144. package/dist/server/libs/defaultMiddleware.d.ts +8 -0
  145. package/dist/server/libs/defaultMiddleware.js +128 -0
  146. package/dist/server/libs/inFlightLimit.d.ts +18 -0
  147. package/dist/server/libs/inFlightLimit.js +17 -0
  148. package/dist/server/libs/index.d.ts +18 -0
  149. package/dist/server/libs/index.js +34 -0
  150. package/dist/server/libs/middlewareManager.js +126 -0
  151. package/dist/server/libs/type.d.ts +22 -0
  152. package/dist/server/libs/type.js +7 -0
  153. package/dist/server/types.d.ts +236 -0
  154. package/dist/server/types.js +7 -0
  155. package/package.json +126 -4
@@ -0,0 +1,11 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ export * from '../core/server/types.js';
8
+ export * from '../core/server/constants/index.js';
9
+ export * from '../core/server/helpers/index.js';
10
+ export { BtpsServer } from './btpsServer.js';
11
+ export * from './types.js';
@@ -0,0 +1,15 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ export * from "../core/server/types.js";
9
+ export * from "../core/server/constants/index.js";
10
+ export * from "../core/server/helpers/index.js";
11
+ import { BtpsServer } from "./btpsServer.js";
12
+ export * from "./types.js";
13
+ export {
14
+ BtpsServer
15
+ };
@@ -0,0 +1,10 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ export declare abstract class RateLimiter {
8
+ abstract isAllowed(identity: string, type?: 'ipAddress' | 'fromIdentity'): Promise<boolean>;
9
+ cleanup(): void;
10
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ class RateLimiter {
9
+
10
+ cleanup() {
11
+ }
12
+ }
13
+ export {
14
+ RateLimiter
15
+ };
@@ -0,0 +1,27 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ import { Transform } from 'stream';
8
+ import { BTPErrorException } from '../../core/error/index.js';
9
+ /** The largest artifact a server can accept unless it sets `maxArtifactSizeKb`: 5 MB. */
10
+ export declare const DEFAULT_MAX_ARTIFACT_SIZE_KB = 5120;
11
+ /** The smallest limit a server may set: 1 MB. */
12
+ export declare const MIN_MAX_ARTIFACT_SIZE_KB = 1024;
13
+ /**
14
+ * The artifact size limit a server uses, in KB. A limit it cannot use as
15
+ * given never stops the server: it is warned about and replaced by the
16
+ * minimum (when too small) or the default (when not a size at all).
17
+ */
18
+ export declare const resolveMaxArtifactSizeKb: (configured: number | undefined) => number;
19
+ /**
20
+ * Passes a connection's bytes through unchanged until one line (one
21
+ * artifact) passes `maxKb`, counted in bytes before anything is decoded or
22
+ * parsed. Then it calls `onTooLarge` once and drops everything the
23
+ * connection sends from that chunk on. So a peer cannot make the server hold
24
+ * more than the limit for any one artifact, and the server can still answer
25
+ * and close gently while the peer finishes sending.
26
+ */
27
+ export declare const artifactSizeGuard: (maxKb: number, onTooLarge: (error: BTPErrorException) => void) => Transform;
@@ -0,0 +1,44 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ import { Transform } from "stream";
9
+ import { BTPErrorException } from "../../core/error/index.js";
10
+ import { BTP_ERROR_ARTIFACT_TOO_LARGE } from "../../core/error/constant.js";
11
+ const DEFAULT_MAX_ARTIFACT_SIZE_KB = 5120, MIN_MAX_ARTIFACT_SIZE_KB = 1024, resolveMaxArtifactSizeKb = (configured) => configured === void 0 ? DEFAULT_MAX_ARTIFACT_SIZE_KB : !Number.isFinite(configured) || configured <= 0 ? (console.warn(
12
+ `[BtpsServer] maxArtifactSizeKb ${configured} is not a usable size; using the default ${DEFAULT_MAX_ARTIFACT_SIZE_KB} KB`
13
+ ), DEFAULT_MAX_ARTIFACT_SIZE_KB) : configured < MIN_MAX_ARTIFACT_SIZE_KB ? (console.warn(
14
+ `[BtpsServer] maxArtifactSizeKb ${configured} is below the ${MIN_MAX_ARTIFACT_SIZE_KB} KB minimum; using ${MIN_MAX_ARTIFACT_SIZE_KB} KB`
15
+ ), MIN_MAX_ARTIFACT_SIZE_KB) : configured, artifactSizeGuard = (maxKb, onTooLarge) => {
16
+ const maxBytes = Math.floor(maxKb * 1024);
17
+ let lineBytes = 0, discarding = !1;
18
+ const refuse = (callback) => {
19
+ discarding = !0, onTooLarge(
20
+ new BTPErrorException({
21
+ ...BTP_ERROR_ARTIFACT_TOO_LARGE,
22
+ message: `${BTP_ERROR_ARTIFACT_TOO_LARGE.message}: ${maxKb} KB`
23
+ })
24
+ ), callback();
25
+ };
26
+ return new Transform({
27
+ transform(chunk, _encoding, callback) {
28
+ if (discarding) return callback();
29
+ let start = 0, newline = chunk.indexOf(10, start);
30
+ for (; newline !== -1; ) {
31
+ if (lineBytes + newline - start > maxBytes) return refuse(callback);
32
+ lineBytes = 0, start = newline + 1, newline = chunk.indexOf(10, start);
33
+ }
34
+ if (lineBytes += chunk.length - start, lineBytes > maxBytes) return refuse(callback);
35
+ callback(null, chunk);
36
+ }
37
+ });
38
+ };
39
+ export {
40
+ DEFAULT_MAX_ARTIFACT_SIZE_KB,
41
+ MIN_MAX_ARTIFACT_SIZE_KB,
42
+ artifactSizeGuard,
43
+ resolveMaxArtifactSizeKb
44
+ };
@@ -0,0 +1,24 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ import { BTPErrorException } from '../../core/error/index.js';
8
+ /** How far a server lets an artifact's `issuedAt` be from its own clock unless it sets `maxArtifactAgeSeconds`: 5 minutes. */
9
+ export declare const DEFAULT_MAX_ARTIFACT_AGE_SECONDS = 300;
10
+ /** The smallest time window a server may set: 1 minute. */
11
+ export declare const MIN_MAX_ARTIFACT_AGE_SECONDS = 60;
12
+ /**
13
+ * The time window a server uses, in seconds. A window it cannot use as given
14
+ * never stops the server: it is warned about and replaced by the minimum
15
+ * (when too small) or the default (when not a number of seconds at all).
16
+ */
17
+ export declare const resolveMaxArtifactAgeSeconds: (configured: number | undefined) => number;
18
+ /**
19
+ * Why an artifact signed at `issuedAt` is outside a window of `maxAgeSeconds`
20
+ * either side of `now`, or undefined when it is inside. The signature covers
21
+ * `issuedAt`, so a copy sent again later cannot be given a new time: once the
22
+ * window has passed, it is refused.
23
+ */
24
+ export declare const artifactTimeWindowError: (issuedAt: string, maxAgeSeconds: number, now?: number) => BTPErrorException | undefined;
@@ -0,0 +1,30 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ import { BTPErrorException } from "../../core/error/index.js";
9
+ import { BTP_ERROR_ARTIFACT_TIME_WINDOW } from "../../core/error/constant.js";
10
+ const DEFAULT_MAX_ARTIFACT_AGE_SECONDS = 300, MIN_MAX_ARTIFACT_AGE_SECONDS = 60, resolveMaxArtifactAgeSeconds = (configured) => configured === void 0 ? DEFAULT_MAX_ARTIFACT_AGE_SECONDS : !Number.isFinite(configured) || configured <= 0 ? (console.warn(
11
+ `[BtpsServer] maxArtifactAgeSeconds ${configured} is not a usable time; using the default ${DEFAULT_MAX_ARTIFACT_AGE_SECONDS} seconds`
12
+ ), DEFAULT_MAX_ARTIFACT_AGE_SECONDS) : configured < MIN_MAX_ARTIFACT_AGE_SECONDS ? (console.warn(
13
+ `[BtpsServer] maxArtifactAgeSeconds ${configured} is below the ${MIN_MAX_ARTIFACT_AGE_SECONDS} second minimum; using ${MIN_MAX_ARTIFACT_AGE_SECONDS} seconds`
14
+ ), MIN_MAX_ARTIFACT_AGE_SECONDS) : configured, artifactTimeWindowError = (issuedAt, maxAgeSeconds, now = Date.now()) => {
15
+ const signedAt = Date.parse(issuedAt);
16
+ if (!(Number.isFinite(signedAt) && Math.abs(now - signedAt) <= maxAgeSeconds * 1e3))
17
+ return new BTPErrorException(
18
+ {
19
+ ...BTP_ERROR_ARTIFACT_TIME_WINDOW,
20
+ message: `${BTP_ERROR_ARTIFACT_TIME_WINDOW.message}: ${maxAgeSeconds} seconds`
21
+ },
22
+ { meta: { issuedAt, maxAgeSeconds } }
23
+ );
24
+ };
25
+ export {
26
+ DEFAULT_MAX_ARTIFACT_AGE_SECONDS,
27
+ MIN_MAX_ARTIFACT_AGE_SECONDS,
28
+ artifactTimeWindowError,
29
+ resolveMaxArtifactAgeSeconds
30
+ };
@@ -0,0 +1,29 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ import { BtpsServer } from '../../server/btpsServer.js';
8
+ import { BtpsServerOptions } from '../../server/types.js';
9
+ /**
10
+ * BtpsServerRegistry keeps track of multiple named BtpsServer instances.
11
+ */
12
+ export declare class BtpsServerRegistry {
13
+ private static servers;
14
+ static register(id: string, server: BtpsServer): void;
15
+ static get(id: string): BtpsServer | undefined;
16
+ static start(id: string): Promise<void>;
17
+ static stop(id: string): void;
18
+ static startAll(): Promise<void>;
19
+ static stopAll(): void;
20
+ static clear(): void;
21
+ }
22
+ /**
23
+ * BtpsServerFactory creates singleton BtpsServer instances from configuration.
24
+ */
25
+ export declare class BtpsServerSingletonFactory {
26
+ private static instance;
27
+ static create(config: BtpsServerOptions): BtpsServer;
28
+ static reset(): void;
29
+ }
@@ -0,0 +1,49 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ import { BtpsServer } from "../../server/btpsServer.js";
9
+ class BtpsServerRegistry {
10
+ static servers = new Map();
11
+ static register(id, server) {
12
+ this.servers.set(id, server);
13
+ }
14
+ static get(id) {
15
+ return this.servers.get(id);
16
+ }
17
+ static async start(id) {
18
+ const server = this.servers.get(id);
19
+ server ? await server.start() : console.warn(`[BtpsServerRegistry] Server with id '${id}' not found.`);
20
+ }
21
+ static stop(id) {
22
+ const server = this.servers.get(id);
23
+ server ? server.stop() : console.warn(`[BtpsServerRegistry] Server with id '${id}' not found.`);
24
+ }
25
+ static async startAll() {
26
+ const startPromises = Array.from(this.servers.values()).map((server) => server.start());
27
+ await Promise.all(startPromises);
28
+ }
29
+ static stopAll() {
30
+ for (const server of this.servers.values())
31
+ server.stop();
32
+ }
33
+ static clear() {
34
+ this.servers.clear();
35
+ }
36
+ }
37
+ class BtpsServerSingletonFactory {
38
+ static instance = null;
39
+ static create(config) {
40
+ return this.instance || (this.instance = new BtpsServer(config)), this.instance;
41
+ }
42
+ static reset() {
43
+ this.instance = null;
44
+ }
45
+ }
46
+ export {
47
+ BtpsServerRegistry,
48
+ BtpsServerSingletonFactory
49
+ };
@@ -0,0 +1,35 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ import type { BtpsServerOptions, ProcessedArtifact, ArtifactResCtx } from '../types.js';
8
+ import type { BTPStatus, BTPServerResponse, BTPAgentArtifact, BTPTransporterArtifact } from '../../core/server/types.js';
9
+ interface BtpsServerInstance {
10
+ start(): Promise<void>;
11
+ stop(): void;
12
+ forwardTo(handler: (msg: ProcessedArtifact) => Promise<void>): void;
13
+ onIncomingArtifact(type: 'Agent' | 'Transporter', handler: ((artifact: BTPAgentArtifact, resCtx: ArtifactResCtx) => void) | ((artifact: BTPTransporterArtifact) => void | Promise<void>)): void;
14
+ getProtocolVersion(): string;
15
+ prepareBtpsResponse(status: BTPStatus, reqId?: string): Omit<BTPServerResponse, 'type'>;
16
+ }
17
+ /**
18
+ * Lightweight factory that uses dynamic imports to avoid bundling the full BtpsServer
19
+ * until it's actually needed. This significantly reduces the initial bundle size.
20
+ */
21
+ export declare class BtpsServerLightweightFactory {
22
+ private static instance;
23
+ static create(config: BtpsServerOptions): Promise<BtpsServerInstance>;
24
+ static reset(): void;
25
+ }
26
+ /**
27
+ * Synchronous factory that creates the server immediately
28
+ * Use this only if you need the server instance right away
29
+ */
30
+ export declare class BtpsServerSyncFactory {
31
+ private static instance;
32
+ static create(config: BtpsServerOptions): Promise<BtpsServerInstance>;
33
+ static reset(): void;
34
+ }
35
+ export {};
@@ -0,0 +1,37 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ class BtpsServerLightweightFactory {
9
+ static instance = null;
10
+ static async create(config) {
11
+ if (!this.instance) {
12
+ const { BtpsServer } = await import("../btpsServer.js");
13
+ this.instance = new BtpsServer(config);
14
+ }
15
+ return this.instance;
16
+ }
17
+ static reset() {
18
+ this.instance = null;
19
+ }
20
+ }
21
+ class BtpsServerSyncFactory {
22
+ static instance = null;
23
+ static async create(config) {
24
+ if (!this.instance) {
25
+ const { BtpsServer } = await import("../btpsServer.js");
26
+ this.instance = new BtpsServer(config);
27
+ }
28
+ return this.instance;
29
+ }
30
+ static reset() {
31
+ this.instance = null;
32
+ }
33
+ }
34
+ export {
35
+ BtpsServerLightweightFactory,
36
+ BtpsServerSyncFactory
37
+ };
@@ -0,0 +1,14 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ import { BtpsServer } from '../../server/btpsServer.js';
8
+ import { BtpsServerOptions } from '../../server/types.js';
9
+ /**
10
+ * BtpsServerFactory creates new BtpsServer instances from configuration.
11
+ */
12
+ export declare class BtpsServerFactory {
13
+ static create(config: BtpsServerOptions): BtpsServer;
14
+ }
@@ -0,0 +1,16 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ import { BtpsServer } from "../../server/btpsServer.js";
9
+ class BtpsServerFactory {
10
+ static create(config) {
11
+ return new BtpsServer(config);
12
+ }
13
+ }
14
+ export {
15
+ BtpsServerFactory
16
+ };
@@ -0,0 +1,13 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ import { BTPErrorException } from '../../core/error/index.js';
8
+ import { IMetricsTracker } from './type.js';
9
+ export declare class BtpsSimpleMetricsTracker implements IMetricsTracker {
10
+ onMessageReceived(sender: string, recipient?: string): void;
11
+ onMessageRejected(sender: string, recipient: string, reason: string): void;
12
+ onError(error: BTPErrorException): void;
13
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ class BtpsSimpleMetricsTracker {
9
+ onMessageReceived(sender, recipient) {
10
+ console.log(`[Metrics] Received message from ${sender}${recipient ? ` to ${recipient}` : ""}`);
11
+ }
12
+ onMessageRejected(sender, recipient, reason) {
13
+ console.warn(`[Metrics] Rejected message from ${sender} to ${recipient}: ${reason}`);
14
+ }
15
+ onError(error) {
16
+ console.error("[Metrics] Error:", error.toJSON());
17
+ }
18
+ }
19
+ export {
20
+ BtpsSimpleMetricsTracker
21
+ };
@@ -0,0 +1,28 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ import { RateLimiter } from './abstractRateLimiter.js';
8
+ import { IRateLimitOptions } from './type.js';
9
+ /**
10
+ * An in-memory example of the RateLimiter contract, for development and tests.
11
+ * Not for production: its counters live in one process, so they are not shared
12
+ * between servers and cost that server memory under a flood. Production limits
13
+ * belong in a shared store such as Redis or Memcached, behind RateLimiter.
14
+ */
15
+ export declare class BtpsSimpleRateLimiter implements RateLimiter {
16
+ private readonly identityLimitPerSec;
17
+ private readonly ipLimitPerSec;
18
+ private readonly cleanupIntervalMs;
19
+ private readonly maxEntries;
20
+ private readonly ipCounters;
21
+ private readonly identityCounters;
22
+ private cleanupTimer?;
23
+ constructor(options?: IRateLimitOptions);
24
+ private startCleanupTimer;
25
+ stopCleanupTimer(): void;
26
+ cleanup(): void;
27
+ isAllowed(identity: string, type: 'ipAddress' | 'fromIdentity'): Promise<boolean>;
28
+ }
@@ -0,0 +1,46 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ class BtpsSimpleRateLimiter {
9
+ identityLimitPerSec;
10
+ ipLimitPerSec;
11
+ cleanupIntervalMs;
12
+ maxEntries;
13
+ ipCounters = new Map();
14
+ identityCounters = new Map();
15
+ cleanupTimer;
16
+ constructor(options = {}) {
17
+ this.identityLimitPerSec = options.fromIdentity ?? 10, this.ipLimitPerSec = options.ipAddress ?? 50, this.cleanupIntervalMs = (options?.cleanupIntervalSec ?? 60) * 1e3, this.maxEntries = options.maxEntries ?? 1e5, this.startCleanupTimer();
18
+ }
19
+ startCleanupTimer() {
20
+ this.cleanupTimer = setInterval(() => this.cleanup(), this.cleanupIntervalMs), this.cleanupTimer.unref();
21
+ }
22
+ stopCleanupTimer() {
23
+ this.cleanupTimer && clearInterval(this.cleanupTimer);
24
+ }
25
+ cleanup() {
26
+ const windowStart = Date.now() - 1e3, filterOld = (map) => {
27
+ for (const [key, { windowStart: ts }] of map.entries())
28
+ ts < windowStart && map.delete(key);
29
+ };
30
+ filterOld(this.ipCounters), filterOld(this.identityCounters);
31
+ }
32
+ async isAllowed(identity, type) {
33
+ const now = Date.now(), windowStart = now - 1e3, counters = type === "ipAddress" ? this.ipCounters : this.identityCounters, limit = type === "ipAddress" ? this.ipLimitPerSec : this.identityLimitPerSec, current = counters.get(identity);
34
+ if (!current || current.windowStart < windowStart) {
35
+ if (counters.delete(identity), counters.size >= this.maxEntries) {
36
+ const oldest = counters.keys().next().value;
37
+ oldest !== void 0 && counters.delete(oldest);
38
+ }
39
+ return counters.set(identity, { count: 1, windowStart: now }), !0;
40
+ }
41
+ return current.count >= limit ? !1 : (current.count++, !0);
42
+ }
43
+ }
44
+ export {
45
+ BtpsSimpleRateLimiter
46
+ };
@@ -0,0 +1,16 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ /** How long a server keeps an idle connection open unless it sets `connectionTimeoutMs`: 30 seconds. */
8
+ export declare const DEFAULT_CONNECTION_TIMEOUT_MS = 30000;
9
+ /**
10
+ * How long the server keeps a connection with nothing in flight, in ms. There
11
+ * is no minimum: a server under heavy load may close idle connections quickly,
12
+ * since a connection is never closed while one of its requests is handled. A
13
+ * value it cannot use never stops the server: it is warned about and replaced
14
+ * by the default.
15
+ */
16
+ export declare const resolveConnectionTimeoutMs: (configured: number | undefined) => number;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ const DEFAULT_CONNECTION_TIMEOUT_MS = 3e4, resolveConnectionTimeoutMs = (configured) => configured === void 0 ? 3e4 : !Number.isFinite(configured) || configured <= 0 ? (console.warn(
9
+ `[BtpsServer] connectionTimeoutMs ${configured} is not a usable time; using the default 30000 ms`
10
+ ), 3e4) : configured;
11
+ export {
12
+ DEFAULT_CONNECTION_TIMEOUT_MS,
13
+ resolveConnectionTimeoutMs
14
+ };
@@ -0,0 +1,8 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+ import { MiddlewareDefinitionArray } from '../types.js';
8
+ export declare function createDefaultMiddleware(): MiddlewareDefinitionArray;
@@ -0,0 +1,128 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) 2025 Bhupendra Tamang
4
+ * Licensed under the Apache License, Version 2.0
5
+ * https://www.apache.org/licenses/LICENSE-2.0
6
+ */
7
+
8
+ import { BTP_ERROR_RATE_LIMITER } from "../../core/error/constant.js";
9
+ import { BtpsSimpleRateLimiter } from "./btpsSimpleRateLimiter.js";
10
+ import { BtpsSimpleMetricsTracker } from "./btpsSimpleMetricsTracker.js";
11
+ const rateLimiter = new BtpsSimpleRateLimiter({
12
+ cleanupIntervalSec: 30,
13
+ fromIdentity: 30,
14
+ ipAddress: 50
15
+ }), metrics = new BtpsSimpleMetricsTracker();
16
+ function createDefaultMiddleware() {
17
+ return [
18
+
19
+ {
20
+ phase: "before",
21
+ step: "parsing",
22
+ priority: 1,
23
+ config: {
24
+ name: "default-ip-rate-limiter",
25
+ enabled: !0
26
+ },
27
+ handler: async (req, res, next) => {
28
+ if (!await rateLimiter.isAllowed(req.remoteAddress, "ipAddress"))
29
+ return metrics.onMessageRejected(req.remoteAddress, "", "Rate limit exceeded"), res.sendError(BTP_ERROR_RATE_LIMITER);
30
+ await next();
31
+ }
32
+ },
33
+
34
+ {
35
+ phase: "after",
36
+ step: "parsing",
37
+ priority: 1,
38
+ config: {
39
+ name: "default-parsing-metrics-tracker",
40
+ enabled: !0
41
+ },
42
+ handler: async (req, res, next) => {
43
+ const { data, error, getIdentity } = req, { to, from } = getIdentity();
44
+ if (data) {
45
+ if (error) {
46
+ error.code === "BTP_ERROR_VALIDATION" ? metrics.onMessageRejected(
47
+ from,
48
+ to,
49
+ JSON.stringify({ message: error.message, data }, null, 2)
50
+ ) : metrics.onError(error);
51
+ return;
52
+ }
53
+ await next();
54
+ }
55
+ }
56
+ },
57
+
58
+
59
+
60
+ {
61
+ phase: "after",
62
+ step: "signatureVerification",
63
+ priority: 1,
64
+ config: {
65
+ name: "default-identity-rate-limiter",
66
+ enabled: !0
67
+ },
68
+ handler: async (req, res, next) => {
69
+ const { error, remoteAddress, getIdentity } = req, { to, from } = getIdentity();
70
+ if (error) {
71
+ metrics.onMessageRejected(from, to, error.message), metrics.onError(error);
72
+ return;
73
+ }
74
+ if (!await rateLimiter.isAllowed(from, "fromIdentity"))
75
+ return metrics.onMessageRejected(remoteAddress, to, "Rate limit exceeded"), res.sendError(BTP_ERROR_RATE_LIMITER);
76
+ await next();
77
+ }
78
+ },
79
+
80
+ {
81
+ phase: "after",
82
+ step: "trustVerification",
83
+ priority: 1,
84
+ config: {
85
+ name: "default-trust-metrics-tracker",
86
+ enabled: !0
87
+ },
88
+ handler: async (req, res, next) => {
89
+ const { error, getIdentity } = req, { to, from } = getIdentity();
90
+ if (error) {
91
+ metrics.onMessageRejected(from, to, error.message);
92
+ return;
93
+ }
94
+ await next();
95
+ }
96
+ },
97
+
98
+ {
99
+ phase: "after",
100
+ step: "onArtifact",
101
+ priority: 1,
102
+ config: {
103
+ name: "default-onMessage-metrics-tracker",
104
+ enabled: !0
105
+ },
106
+ handler: async (req, _res, next) => {
107
+ const { getIdentity } = req, { to, from } = getIdentity();
108
+ from && to && metrics.onMessageReceived(from, to), await next();
109
+ }
110
+ },
111
+
112
+ {
113
+ phase: "before",
114
+ step: "onError",
115
+ priority: 1,
116
+ config: {
117
+ name: "default-error-logger",
118
+ enabled: !0
119
+ },
120
+ handler: async (req, _res, next) => {
121
+ req.error && metrics.onError(req.error), await next();
122
+ }
123
+ }
124
+ ];
125
+ }
126
+ export {
127
+ createDefaultMiddleware
128
+ };