@aura-payments/mcp-server 1.0.1 → 1.2.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 (7) hide show
  1. package/dist/bin.js +593 -18
  2. package/dist/bin.mjs +593 -18
  3. package/dist/index.d.mts +77 -8
  4. package/dist/index.d.ts +77 -8
  5. package/dist/index.js +586 -18
  6. package/dist/index.mjs +579 -19
  7. package/package.json +6 -4
package/dist/index.d.mts CHANGED
@@ -1,6 +1,66 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
2
  import { AuraClient } from '@aura-payments/sdk';
3
3
 
4
+ /**
5
+ * API key parsing and validation for the Aura MCP server.
6
+ *
7
+ * Deliberately dependency-free: this module imports nothing (not even the
8
+ * Aura SDK) so it can be unit-tested in isolation and imported from the
9
+ * startup banner without pulling the whole client graph into scope.
10
+ *
11
+ * SECURITY: no function here ever returns the full key. `maskApiKey` reveals
12
+ * at most half of the key (capped at 8 characters) so a malformed-key error
13
+ * can identify WHICH key is wrong without ever writing the secret into a log,
14
+ * a stderr banner, or an MCP tool result.
15
+ */
16
+ /**
17
+ * Recognized API key prefixes.
18
+ *
19
+ * `sk_` = secret key (server-side), `pk_` = publishable key. The middle
20
+ * segment selects the environment the key is bound to; a key issued for one
21
+ * environment is never valid in the other.
22
+ */
23
+ declare const API_KEY_PREFIXES: readonly ["sk_test_", "sk_live_", "pk_test_", "pk_live_"];
24
+ type AuraApiKeyPrefix = (typeof API_KEY_PREFIXES)[number];
25
+ /** Which Aura environment a key is bound to. */
26
+ type AuraKeyMode = 'test' | 'live';
27
+ interface ParsedAuraApiKey {
28
+ /** The matched prefix, e.g. `pk_test_`. Safe to log — carries no secret. */
29
+ prefix: AuraApiKeyPrefix;
30
+ /** Resolved environment, derived from the prefix. */
31
+ mode: AuraKeyMode;
32
+ }
33
+ /**
34
+ * Redact a key for display.
35
+ *
36
+ * Reveals `min(8, floor(length / 2))` leading characters, so the result can
37
+ * never contain the whole key for any input of length >= 1. The length is
38
+ * appended because "wrong length" is the most common misconfiguration (a
39
+ * truncated paste) and it leaks nothing.
40
+ */
41
+ declare function maskApiKey(apiKey: string): string;
42
+ /**
43
+ * Parse and validate `AURA_API_KEY`.
44
+ *
45
+ * @throws {MissingAuraApiKeyError} when the key is absent or blank.
46
+ * @throws {MalformedAuraApiKeyError} when the key carries no recognized prefix.
47
+ */
48
+ declare function parseApiKey(apiKey: string | undefined): ParsedAuraApiKey;
49
+ /**
50
+ * Resolve the environment for display without throwing.
51
+ *
52
+ * The startup banner must never crash the process — an unusable key still has
53
+ * to produce a running server whose FIRST TOOL CALL returns a clear error, so
54
+ * the MCP host surfaces something actionable instead of a dead subprocess.
55
+ */
56
+ declare function resolveKeyMode(apiKey: string | undefined): AuraKeyMode | 'unconfigured' | 'invalid';
57
+ declare class MissingAuraApiKeyError extends Error {
58
+ constructor();
59
+ }
60
+ declare class MalformedAuraApiKeyError extends Error {
61
+ constructor(apiKey: string);
62
+ }
63
+
4
64
  /**
5
65
  * Aura SDK client factory for the MCP server.
6
66
  *
@@ -9,20 +69,22 @@ import { AuraClient } from '@aura-payments/sdk';
9
69
  * the `env` field in mcp.json). The client is created lazily on first tool
10
70
  * invocation so missing env doesn't crash the server during the MCP handshake
11
71
  * — instead, the FIRST tool call returns a clear error the LLM can act on.
72
+ *
73
+ * The key is validated for BOTH presence and format before it is ever put on
74
+ * the wire. A malformed key would otherwise fail as an opaque 401 from the
75
+ * platform, which is indistinguishable from a revoked key — the local check
76
+ * turns that into an actionable configuration error.
12
77
  */
13
78
 
14
79
  declare function getClient(): AuraClient;
15
- declare class MissingAuraApiKeyError extends Error {
16
- constructor();
17
- }
18
80
 
19
81
  /**
20
82
  * Aura Payments MCP Server — programmatic entry point.
21
83
  *
22
- * The MCP server exposes Aura's escrow, agent, mandate, and wallet primitives
23
- * as Model Context Protocol tools and resources, so AI agents (Claude,
24
- * Cursor, Continue, custom orchestrators) can drive Aura natively over
25
- * stdio without writing HTTP boilerplate.
84
+ * The MCP server exposes Aura's escrow, agent, mandate, wallet, and webhook
85
+ * primitives as Model Context Protocol tools and resources, so AI agents
86
+ * (Claude, Cursor, Continue, custom orchestrators) can drive Aura natively
87
+ * over stdio without writing HTTP boilerplate.
26
88
  *
27
89
  * This file exports `createServer()` for programmatic use (tests, custom
28
90
  * transports, embedding in other MCP hosts). For the standalone binary,
@@ -33,10 +95,17 @@ declare class MissingAuraApiKeyError extends Error {
33
95
  * shape, idempotency, retries, and error mapping.
34
96
  */
35
97
 
98
+ declare const SERVER_NAME = "aura-payments";
99
+ declare const SERVER_VERSION = "1.2.0";
36
100
  interface CreateServerOptions {
37
101
  name?: string;
38
102
  version?: string;
39
103
  }
104
+ /**
105
+ * Names of the tools registered on `server`, in registration order.
106
+ * Returns an empty array for a server this module did not build.
107
+ */
108
+ declare function getRegisteredToolNames(server: McpServer): readonly string[];
40
109
  /**
41
110
  * Build a fully-configured MCP server with all Aura tools and resources
42
111
  * registered. The caller is responsible for connecting it to a transport
@@ -44,4 +113,4 @@ interface CreateServerOptions {
44
113
  */
45
114
  declare function createServer(options?: CreateServerOptions): McpServer;
46
115
 
47
- export { type CreateServerOptions, MissingAuraApiKeyError, createServer, getClient };
116
+ export { API_KEY_PREFIXES, type AuraKeyMode, type CreateServerOptions, MalformedAuraApiKeyError, MissingAuraApiKeyError, type ParsedAuraApiKey, SERVER_NAME, SERVER_VERSION, createServer, getClient, getRegisteredToolNames, maskApiKey, parseApiKey, resolveKeyMode };
package/dist/index.d.ts CHANGED
@@ -1,6 +1,66 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
2
  import { AuraClient } from '@aura-payments/sdk';
3
3
 
4
+ /**
5
+ * API key parsing and validation for the Aura MCP server.
6
+ *
7
+ * Deliberately dependency-free: this module imports nothing (not even the
8
+ * Aura SDK) so it can be unit-tested in isolation and imported from the
9
+ * startup banner without pulling the whole client graph into scope.
10
+ *
11
+ * SECURITY: no function here ever returns the full key. `maskApiKey` reveals
12
+ * at most half of the key (capped at 8 characters) so a malformed-key error
13
+ * can identify WHICH key is wrong without ever writing the secret into a log,
14
+ * a stderr banner, or an MCP tool result.
15
+ */
16
+ /**
17
+ * Recognized API key prefixes.
18
+ *
19
+ * `sk_` = secret key (server-side), `pk_` = publishable key. The middle
20
+ * segment selects the environment the key is bound to; a key issued for one
21
+ * environment is never valid in the other.
22
+ */
23
+ declare const API_KEY_PREFIXES: readonly ["sk_test_", "sk_live_", "pk_test_", "pk_live_"];
24
+ type AuraApiKeyPrefix = (typeof API_KEY_PREFIXES)[number];
25
+ /** Which Aura environment a key is bound to. */
26
+ type AuraKeyMode = 'test' | 'live';
27
+ interface ParsedAuraApiKey {
28
+ /** The matched prefix, e.g. `pk_test_`. Safe to log — carries no secret. */
29
+ prefix: AuraApiKeyPrefix;
30
+ /** Resolved environment, derived from the prefix. */
31
+ mode: AuraKeyMode;
32
+ }
33
+ /**
34
+ * Redact a key for display.
35
+ *
36
+ * Reveals `min(8, floor(length / 2))` leading characters, so the result can
37
+ * never contain the whole key for any input of length >= 1. The length is
38
+ * appended because "wrong length" is the most common misconfiguration (a
39
+ * truncated paste) and it leaks nothing.
40
+ */
41
+ declare function maskApiKey(apiKey: string): string;
42
+ /**
43
+ * Parse and validate `AURA_API_KEY`.
44
+ *
45
+ * @throws {MissingAuraApiKeyError} when the key is absent or blank.
46
+ * @throws {MalformedAuraApiKeyError} when the key carries no recognized prefix.
47
+ */
48
+ declare function parseApiKey(apiKey: string | undefined): ParsedAuraApiKey;
49
+ /**
50
+ * Resolve the environment for display without throwing.
51
+ *
52
+ * The startup banner must never crash the process — an unusable key still has
53
+ * to produce a running server whose FIRST TOOL CALL returns a clear error, so
54
+ * the MCP host surfaces something actionable instead of a dead subprocess.
55
+ */
56
+ declare function resolveKeyMode(apiKey: string | undefined): AuraKeyMode | 'unconfigured' | 'invalid';
57
+ declare class MissingAuraApiKeyError extends Error {
58
+ constructor();
59
+ }
60
+ declare class MalformedAuraApiKeyError extends Error {
61
+ constructor(apiKey: string);
62
+ }
63
+
4
64
  /**
5
65
  * Aura SDK client factory for the MCP server.
6
66
  *
@@ -9,20 +69,22 @@ import { AuraClient } from '@aura-payments/sdk';
9
69
  * the `env` field in mcp.json). The client is created lazily on first tool
10
70
  * invocation so missing env doesn't crash the server during the MCP handshake
11
71
  * — instead, the FIRST tool call returns a clear error the LLM can act on.
72
+ *
73
+ * The key is validated for BOTH presence and format before it is ever put on
74
+ * the wire. A malformed key would otherwise fail as an opaque 401 from the
75
+ * platform, which is indistinguishable from a revoked key — the local check
76
+ * turns that into an actionable configuration error.
12
77
  */
13
78
 
14
79
  declare function getClient(): AuraClient;
15
- declare class MissingAuraApiKeyError extends Error {
16
- constructor();
17
- }
18
80
 
19
81
  /**
20
82
  * Aura Payments MCP Server — programmatic entry point.
21
83
  *
22
- * The MCP server exposes Aura's escrow, agent, mandate, and wallet primitives
23
- * as Model Context Protocol tools and resources, so AI agents (Claude,
24
- * Cursor, Continue, custom orchestrators) can drive Aura natively over
25
- * stdio without writing HTTP boilerplate.
84
+ * The MCP server exposes Aura's escrow, agent, mandate, wallet, and webhook
85
+ * primitives as Model Context Protocol tools and resources, so AI agents
86
+ * (Claude, Cursor, Continue, custom orchestrators) can drive Aura natively
87
+ * over stdio without writing HTTP boilerplate.
26
88
  *
27
89
  * This file exports `createServer()` for programmatic use (tests, custom
28
90
  * transports, embedding in other MCP hosts). For the standalone binary,
@@ -33,10 +95,17 @@ declare class MissingAuraApiKeyError extends Error {
33
95
  * shape, idempotency, retries, and error mapping.
34
96
  */
35
97
 
98
+ declare const SERVER_NAME = "aura-payments";
99
+ declare const SERVER_VERSION = "1.2.0";
36
100
  interface CreateServerOptions {
37
101
  name?: string;
38
102
  version?: string;
39
103
  }
104
+ /**
105
+ * Names of the tools registered on `server`, in registration order.
106
+ * Returns an empty array for a server this module did not build.
107
+ */
108
+ declare function getRegisteredToolNames(server: McpServer): readonly string[];
40
109
  /**
41
110
  * Build a fully-configured MCP server with all Aura tools and resources
42
111
  * registered. The caller is responsible for connecting it to a transport
@@ -44,4 +113,4 @@ interface CreateServerOptions {
44
113
  */
45
114
  declare function createServer(options?: CreateServerOptions): McpServer;
46
115
 
47
- export { type CreateServerOptions, MissingAuraApiKeyError, createServer, getClient };
116
+ export { API_KEY_PREFIXES, type AuraKeyMode, type CreateServerOptions, MalformedAuraApiKeyError, MissingAuraApiKeyError, type ParsedAuraApiKey, SERVER_NAME, SERVER_VERSION, createServer, getClient, getRegisteredToolNames, maskApiKey, parseApiKey, resolveKeyMode };