@agentapps/station 0.0.0-stage → 0.2.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.
- package/LICENSE +21 -0
- package/README.md +58 -2
- package/dist/api-key-store.d.ts +46 -0
- package/dist/api-key-store.d.ts.map +1 -0
- package/dist/api-key-store.js +84 -0
- package/dist/api-key-store.js.map +1 -0
- package/dist/app-station.d.ts +129 -0
- package/dist/app-station.d.ts.map +1 -0
- package/dist/app-station.js +706 -0
- package/dist/app-station.js.map +1 -0
- package/dist/approval-manager.d.ts +75 -0
- package/dist/approval-manager.d.ts.map +1 -0
- package/dist/approval-manager.js +96 -0
- package/dist/approval-manager.js.map +1 -0
- package/dist/document-store.d.ts +86 -0
- package/dist/document-store.d.ts.map +1 -0
- package/dist/document-store.js +230 -0
- package/dist/document-store.js.map +1 -0
- package/dist/file-handlers/object-store.d.ts +113 -0
- package/dist/file-handlers/object-store.d.ts.map +1 -0
- package/dist/file-handlers/object-store.js +273 -0
- package/dist/file-handlers/object-store.js.map +1 -0
- package/dist/file-handlers/signed-url.d.ts +44 -0
- package/dist/file-handlers/signed-url.d.ts.map +1 -0
- package/dist/file-handlers/signed-url.js +68 -0
- package/dist/file-handlers/signed-url.js.map +1 -0
- package/dist/file-handlers/volume-handlers.d.ts +136 -0
- package/dist/file-handlers/volume-handlers.d.ts.map +1 -0
- package/dist/file-handlers/volume-handlers.js +426 -0
- package/dist/file-handlers/volume-handlers.js.map +1 -0
- package/dist/in-process-runtime.d.ts +49 -0
- package/dist/in-process-runtime.d.ts.map +1 -0
- package/dist/in-process-runtime.js +50 -0
- package/dist/in-process-runtime.js.map +1 -0
- package/dist/index.d.ts +27 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +34 -0
- package/dist/index.js.map +1 -0
- package/dist/local-process-runtime.d.ts +28 -0
- package/dist/local-process-runtime.d.ts.map +1 -0
- package/dist/local-process-runtime.js +134 -0
- package/dist/local-process-runtime.js.map +1 -0
- package/dist/oauth-manager.d.ts +90 -0
- package/dist/oauth-manager.d.ts.map +1 -0
- package/dist/oauth-manager.js +148 -0
- package/dist/oauth-manager.js.map +1 -0
- package/dist/oauth-pages.d.ts +9 -0
- package/dist/oauth-pages.d.ts.map +1 -0
- package/dist/oauth-pages.js +59 -0
- package/dist/oauth-pages.js.map +1 -0
- package/dist/permission-enforcer.d.ts +52 -0
- package/dist/permission-enforcer.d.ts.map +1 -0
- package/dist/permission-enforcer.js +144 -0
- package/dist/permission-enforcer.js.map +1 -0
- package/dist/policy-store.d.ts +34 -0
- package/dist/policy-store.d.ts.map +1 -0
- package/dist/policy-store.js +35 -0
- package/dist/policy-store.js.map +1 -0
- package/dist/secrets-manager.d.ts +32 -0
- package/dist/secrets-manager.d.ts.map +1 -0
- package/dist/secrets-manager.js +12 -0
- package/dist/secrets-manager.js.map +1 -0
- package/dist/server.d.ts +383 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +1974 -0
- package/dist/server.js.map +1 -0
- package/dist/telemetry.d.ts +9 -0
- package/dist/telemetry.d.ts.map +1 -0
- package/dist/telemetry.js +9 -0
- package/dist/telemetry.js.map +1 -0
- package/dist/types.d.ts +47 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +9 -0
- package/dist/types.js.map +1 -0
- package/package.json +40 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Agent Apps
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,59 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @agentapps/station
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Agent App AppStation — instance lifecycle, traffic proxy, runtime adapters, and backpressure management.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @agentapps/station
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Usage
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { AppStation, InProcessRuntime } from '@agentapps/station';
|
|
15
|
+
import type { AppFactory } from '@agentapps/station';
|
|
16
|
+
|
|
17
|
+
const appFactory: AppFactory = (transport) => {
|
|
18
|
+
// Wire your app to the transport
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
const runtime = new InProcessRuntime(appFactory);
|
|
22
|
+
|
|
23
|
+
const controller = new AppStation({
|
|
24
|
+
appId: 'app.hello',
|
|
25
|
+
appVersion: '1.0.0',
|
|
26
|
+
runtime,
|
|
27
|
+
mode: 'on-demand',
|
|
28
|
+
openTimeoutMs: 60_000,
|
|
29
|
+
maxInflightPerSession: 32,
|
|
30
|
+
idleTimeoutMs: 30 * 60 * 1000,
|
|
31
|
+
maxInstances: 10,
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import { AppStation, InProcessRuntime } from '@agentapps/station';
|
|
37
|
+
|
|
38
|
+
// Standalone mode — one shared instance
|
|
39
|
+
const controller = new AppStation({
|
|
40
|
+
appId: 'app.hello',
|
|
41
|
+
appVersion: '1.0.0',
|
|
42
|
+
runtime: new InProcessRuntime(appFactory),
|
|
43
|
+
mode: 'standalone',
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## API
|
|
48
|
+
|
|
49
|
+
- **`AppStation`** — Core controller class. Manages control plane (handshake, sessions, health), session plane (proxy to instances), callbacks (secret/auth proxy with session validation), lifecycle (spawn, idle teardown, watchdog), and backpressure (max in-flight per session, max instances).
|
|
50
|
+
- **`AppStationConfig`** — Configuration: `appId`, `appVersion`, `runtime`, `openTimeoutMs`, `maxInflightPerSession`, `idleTimeoutMs`, `maxInstances`.
|
|
51
|
+
- **`InProcessRuntime`** — Runtime adapter that runs the app factory in the same process. Useful for testing and dev mode.
|
|
52
|
+
- **`RuntimeAdapter`** — Interface for custom runtime adapters (in-process, child process).
|
|
53
|
+
- **`AppFactory`** — Factory function `(transport: Transport) => void | Promise<void>` that wires an app to a transport.
|
|
54
|
+
- **`InstanceHandle`** — Handle to a running instance: `send(msg)`, `onMessage(handler)`, `terminate()`.
|
|
55
|
+
- **`SpawnConfig`** — Spawn configuration passed to the runtime adapter.
|
|
56
|
+
|
|
57
|
+
## License
|
|
58
|
+
|
|
59
|
+
MIT
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ApiKeyStore — persistence layer for API key records.
|
|
3
|
+
*
|
|
4
|
+
* API keys authenticate callers and link them to a Policy (permission
|
|
5
|
+
* policy). Keys are stored as SHA-256 hashes — the raw key is returned
|
|
6
|
+
* exactly once at creation and never persisted.
|
|
7
|
+
*
|
|
8
|
+
* Pluggable: in-memory for dev/tests, database-backed for production.
|
|
9
|
+
*/
|
|
10
|
+
import type { ApiKeyRecord } from '@agentapps/protocol';
|
|
11
|
+
/** Compute the SHA-256 hex digest of a raw API key. */
|
|
12
|
+
export declare function hashApiKey(raw: string): string;
|
|
13
|
+
/** Generate a new API key with `aak_` prefix (32 random hex chars). */
|
|
14
|
+
export declare function generateApiKey(): {
|
|
15
|
+
raw: string;
|
|
16
|
+
hash: string;
|
|
17
|
+
prefix: string;
|
|
18
|
+
};
|
|
19
|
+
export interface ApiKeyStore {
|
|
20
|
+
/** Store a new API key record. */
|
|
21
|
+
create(record: ApiKeyRecord): Promise<void>;
|
|
22
|
+
/** Look up by key hash (the hot-path for every authenticated request). */
|
|
23
|
+
getByHash(keyHash: string): Promise<ApiKeyRecord | null>;
|
|
24
|
+
/** Look up by ID (for management). */
|
|
25
|
+
getById(id: string): Promise<ApiKeyRecord | null>;
|
|
26
|
+
/** List all keys (optionally filtered). Returns records without keyHash. */
|
|
27
|
+
list(filter?: {
|
|
28
|
+
userId?: string;
|
|
29
|
+
}): Promise<ApiKeyRecord[]>;
|
|
30
|
+
/** Soft-revoke a key by ID. Returns true if found. */
|
|
31
|
+
revoke(id: string): Promise<boolean>;
|
|
32
|
+
}
|
|
33
|
+
export declare class InMemoryApiKeyStore implements ApiKeyStore {
|
|
34
|
+
private readonly byId;
|
|
35
|
+
private readonly byHash;
|
|
36
|
+
create(record: ApiKeyRecord): Promise<void>;
|
|
37
|
+
getByHash(keyHash: string): Promise<ApiKeyRecord | null>;
|
|
38
|
+
getById(id: string): Promise<ApiKeyRecord | null>;
|
|
39
|
+
list(filter?: {
|
|
40
|
+
userId?: string;
|
|
41
|
+
}): Promise<ApiKeyRecord[]>;
|
|
42
|
+
revoke(id: string): Promise<boolean>;
|
|
43
|
+
/** Test helper: get the current count. */
|
|
44
|
+
get size(): number;
|
|
45
|
+
}
|
|
46
|
+
//# sourceMappingURL=api-key-store.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"api-key-store.d.ts","sourceRoot":"","sources":["../src/api-key-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMxD,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,uEAAuE;AACvE,wBAAgB,cAAc,IAAI;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAK9E;AAMD,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C,0EAA0E;IAC1E,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAEzD,sCAAsC;IACtC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAElD,4EAA4E;IAC5E,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE5D,sDAAsD;IACtD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAMD,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmC;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IAE9C,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA4BxD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAKjD,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAW3D,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ1C,0CAA0C;IAC1C,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ApiKeyStore — persistence layer for API key records.
|
|
3
|
+
*
|
|
4
|
+
* API keys authenticate callers and link them to a Policy (permission
|
|
5
|
+
* policy). Keys are stored as SHA-256 hashes — the raw key is returned
|
|
6
|
+
* exactly once at creation and never persisted.
|
|
7
|
+
*
|
|
8
|
+
* Pluggable: in-memory for dev/tests, database-backed for production.
|
|
9
|
+
*/
|
|
10
|
+
import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
|
|
11
|
+
// ---------------------------------------------------------------------------
|
|
12
|
+
// Helpers
|
|
13
|
+
// ---------------------------------------------------------------------------
|
|
14
|
+
/** Compute the SHA-256 hex digest of a raw API key. */
|
|
15
|
+
export function hashApiKey(raw) {
|
|
16
|
+
return createHash('sha256').update(raw).digest('hex');
|
|
17
|
+
}
|
|
18
|
+
/** Generate a new API key with `aak_` prefix (32 random hex chars). */
|
|
19
|
+
export function generateApiKey() {
|
|
20
|
+
const bytes = randomBytes(16); // 16 bytes = 32 hex chars
|
|
21
|
+
const hex = bytes.toString('hex');
|
|
22
|
+
const raw = `aak_${hex}`;
|
|
23
|
+
return { raw, hash: hashApiKey(raw), prefix: raw.slice(0, 12) };
|
|
24
|
+
}
|
|
25
|
+
// ---------------------------------------------------------------------------
|
|
26
|
+
// In-memory implementation (dev/test)
|
|
27
|
+
// ---------------------------------------------------------------------------
|
|
28
|
+
export class InMemoryApiKeyStore {
|
|
29
|
+
byId = new Map();
|
|
30
|
+
byHash = new Map(); // hash -> id
|
|
31
|
+
async create(record) {
|
|
32
|
+
this.byId.set(record.id, { ...record });
|
|
33
|
+
this.byHash.set(record.keyHash, record.id);
|
|
34
|
+
}
|
|
35
|
+
async getByHash(keyHash) {
|
|
36
|
+
// Walk the hash index using timing-safe comparison to avoid
|
|
37
|
+
// leaking which hash prefix matched via timing side-channels.
|
|
38
|
+
const keyHashBuf = Buffer.from(keyHash, 'hex');
|
|
39
|
+
let matchedId;
|
|
40
|
+
for (const [storedHash, id] of this.byHash) {
|
|
41
|
+
const storedBuf = Buffer.from(storedHash, 'hex');
|
|
42
|
+
if (storedBuf.length === keyHashBuf.length && timingSafeEqual(storedBuf, keyHashBuf)) {
|
|
43
|
+
matchedId = id;
|
|
44
|
+
break;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
if (!matchedId)
|
|
48
|
+
return null;
|
|
49
|
+
const record = this.byId.get(matchedId);
|
|
50
|
+
if (!record)
|
|
51
|
+
return null;
|
|
52
|
+
// Skip revoked keys.
|
|
53
|
+
if (record.revokedAt)
|
|
54
|
+
return null;
|
|
55
|
+
// Skip expired keys.
|
|
56
|
+
if (record.expiresAt && new Date(record.expiresAt) <= new Date())
|
|
57
|
+
return null;
|
|
58
|
+
return { ...record };
|
|
59
|
+
}
|
|
60
|
+
async getById(id) {
|
|
61
|
+
const record = this.byId.get(id);
|
|
62
|
+
return record ? { ...record } : null;
|
|
63
|
+
}
|
|
64
|
+
async list(filter) {
|
|
65
|
+
let records = [...this.byId.values()];
|
|
66
|
+
if (filter?.userId) {
|
|
67
|
+
records = records.filter((r) => r.identity.userId === filter.userId);
|
|
68
|
+
}
|
|
69
|
+
// Return copies without keyHash.
|
|
70
|
+
return records.map(({ keyHash: _, ...rest }) => rest);
|
|
71
|
+
}
|
|
72
|
+
async revoke(id) {
|
|
73
|
+
const record = this.byId.get(id);
|
|
74
|
+
if (!record)
|
|
75
|
+
return false;
|
|
76
|
+
record.revokedAt = new Date().toISOString();
|
|
77
|
+
return true;
|
|
78
|
+
}
|
|
79
|
+
/** Test helper: get the current count. */
|
|
80
|
+
get size() {
|
|
81
|
+
return this.byId.size;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
//# sourceMappingURL=api-key-store.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"api-key-store.js","sourceRoot":"","sources":["../src/api-key-store.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Agent App AppStation — core logic.
|
|
3
|
+
*
|
|
4
|
+
* The per-app-family component that owns instance lifecycle and proxies
|
|
5
|
+
* all traffic between host and instances. Handles:
|
|
6
|
+
* - Control plane: initialize, session_open/close, controller_health
|
|
7
|
+
* - Session plane: proxy to/from the correct instance
|
|
8
|
+
* - Requests: proxy instance→host secret/auth requests (with security)
|
|
9
|
+
* - Lifecycle: spawn timeout, idle teardown, session_status notifications
|
|
10
|
+
* - Backpressure: max in-flight per session, max instances
|
|
11
|
+
*
|
|
12
|
+
* Spec: docs/specs/agent-apps/controller-protocol.md
|
|
13
|
+
*/
|
|
14
|
+
import { type Transport } from '@agentapps/protocol';
|
|
15
|
+
import { type TelemetryProvider } from './telemetry.js';
|
|
16
|
+
import type { RuntimeAdapter } from './types.js';
|
|
17
|
+
/** AppStation configuration. */
|
|
18
|
+
export interface AppStationConfig {
|
|
19
|
+
/** App catalog id (e.g., 'app.hello'). */
|
|
20
|
+
appId: string;
|
|
21
|
+
/** App version. */
|
|
22
|
+
appVersion: string;
|
|
23
|
+
/** Runtime adapter for spawning instances. */
|
|
24
|
+
runtime: RuntimeAdapter;
|
|
25
|
+
/** Session open timeout in ms (default: 60 000). */
|
|
26
|
+
openTimeoutMs?: number;
|
|
27
|
+
/** Max in-flight requests per session (default: 32). */
|
|
28
|
+
maxInflightPerSession?: number;
|
|
29
|
+
/** Idle timeout before instance teardown in ms (default: 30 min). */
|
|
30
|
+
idleTimeoutMs?: number;
|
|
31
|
+
/** Max concurrent instances (default: Infinity). */
|
|
32
|
+
maxInstances?: number;
|
|
33
|
+
/** Optional telemetry provider for metrics and tracing. */
|
|
34
|
+
telemetry?: TelemetryProvider;
|
|
35
|
+
/**
|
|
36
|
+
* Decide the Volume mount path for a new Instance from its `session_open`
|
|
37
|
+
* (VOL-REQ-5). Returning `undefined` means no mount.
|
|
38
|
+
*/
|
|
39
|
+
resolveMountPath?: (open: {
|
|
40
|
+
installationId: string;
|
|
41
|
+
tenant: {
|
|
42
|
+
userId: string;
|
|
43
|
+
workspaceId?: string;
|
|
44
|
+
};
|
|
45
|
+
effectivePermissions?: {
|
|
46
|
+
permissions?: {
|
|
47
|
+
volume?: boolean;
|
|
48
|
+
};
|
|
49
|
+
};
|
|
50
|
+
}) => string | undefined;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Agent App AppStation.
|
|
54
|
+
*
|
|
55
|
+
* Usage:
|
|
56
|
+
* ```ts
|
|
57
|
+
* const ctrl = new AppStation({ appId, appVersion, runtime });
|
|
58
|
+
* ctrl.accept(transport); // host connects
|
|
59
|
+
* // ... host sends initialize, session_open, tool_call, etc.
|
|
60
|
+
* await ctrl.shutdown();
|
|
61
|
+
* ```
|
|
62
|
+
*/
|
|
63
|
+
export declare class AppStation {
|
|
64
|
+
private readonly config;
|
|
65
|
+
private initialized;
|
|
66
|
+
/** The Host behind this connection, as declared at initialize (HOSTCAP-REQ-2). */
|
|
67
|
+
private host;
|
|
68
|
+
/** Tenant a single-user Host is bound to by its first session (HOSTCAP-REQ-6). */
|
|
69
|
+
private boundUserId;
|
|
70
|
+
private sessions;
|
|
71
|
+
private instances;
|
|
72
|
+
private hostTransport;
|
|
73
|
+
private hostUnsub;
|
|
74
|
+
private readonly openTimeoutMs;
|
|
75
|
+
private readonly maxInflight;
|
|
76
|
+
private readonly idleTimeoutMs;
|
|
77
|
+
private readonly maxInstances;
|
|
78
|
+
private readonly telemetry;
|
|
79
|
+
/** Track promptIds per session to prevent replay attacks. */
|
|
80
|
+
private readonly promptIds;
|
|
81
|
+
constructor(config: AppStationConfig);
|
|
82
|
+
/** Accept a host connection on the given transport. */
|
|
83
|
+
accept(transport: Transport): void;
|
|
84
|
+
/** Shut down the app station and all sessions. */
|
|
85
|
+
shutdown(): Promise<void>;
|
|
86
|
+
/** Number of active sessions. */
|
|
87
|
+
get sessionCount(): number;
|
|
88
|
+
/** Number of live instances. */
|
|
89
|
+
get instanceCount(): number;
|
|
90
|
+
private handleHostMessage;
|
|
91
|
+
/** REQ-2: Handshake and capability negotiation. */
|
|
92
|
+
private handleInitialize;
|
|
93
|
+
/** REQ-4, REQ-5: Tenant session open (idempotent, with instance reuse). */
|
|
94
|
+
private handleSessionOpen;
|
|
95
|
+
/** REQ-4: Session close. Does NOT immediately stop the instance (REQ-4). */
|
|
96
|
+
private handleSessionClose;
|
|
97
|
+
/** REQ-8: Aggregated app station health. */
|
|
98
|
+
private handleControllerHealth;
|
|
99
|
+
private routeToInstance;
|
|
100
|
+
/**
|
|
101
|
+
* Relay a message from an instance to the host.
|
|
102
|
+
*
|
|
103
|
+
* Security (REQ-7): validates sessionId on request types to prevent
|
|
104
|
+
* a compromised instance from reading another tenant's secrets.
|
|
105
|
+
*/
|
|
106
|
+
private relayInstanceMessage;
|
|
107
|
+
private resetIdleTimer;
|
|
108
|
+
private handleIdleTimeout;
|
|
109
|
+
/** Emit a session_status notification to the host (REQ-5). */
|
|
110
|
+
private emitSessionStatus;
|
|
111
|
+
/** Send a message to the host. */
|
|
112
|
+
/**
|
|
113
|
+
* Answer an Instance's Request with PERMISSION_DENIED when the Permission
|
|
114
|
+
* it needs is not among the session's Effective Permissions. Returns true
|
|
115
|
+
* when the Request was answered here and must not reach the Host.
|
|
116
|
+
*
|
|
117
|
+
* @spec POLICY-REQ-8
|
|
118
|
+
*/
|
|
119
|
+
private denyByPermission;
|
|
120
|
+
private hostSend;
|
|
121
|
+
/**
|
|
122
|
+
* Tell the Instance its session is established and which Host is behind it
|
|
123
|
+
* (HOSTCAP-REQ-2), so the SDK can expose `ctx.host`.
|
|
124
|
+
*/
|
|
125
|
+
private notifySessionOpened;
|
|
126
|
+
/** Send an error response to the host. */
|
|
127
|
+
private sendError;
|
|
128
|
+
}
|
|
129
|
+
//# sourceMappingURL=app-station.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"app-station.d.ts","sourceRoot":"","sources":["../src/app-station.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAKL,KAAK,SAAS,EAEf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjE,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,OAAO,EAAE,cAAc,CAAC;IACxB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE;QACxB,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACjD,oBAAoB,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE;gBAAE,MAAM,CAAC,EAAE,OAAO,CAAA;aAAE,CAAA;SAAE,CAAC;KAC/D,KAAK,MAAM,GAAG,SAAS,CAAC;CAC1B;AAwFD;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IAwBT,OAAO,CAAC,QAAQ,CAAC,MAAM;IAvBnC,OAAO,CAAC,WAAW,CAAS;IAC5B,kFAAkF;IAClF,OAAO,CAAC,IAAI,CAIoC;IAChD,kFAAkF;IAClF,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,SAAS,CAA4B;IAE7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAE9C,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;gBAE/B,MAAM,EAAE,gBAAgB;IAYrD,uDAAuD;IACvD,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAUlC,kDAAkD;IAC5C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB/B,iCAAiC;IACjC,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,gCAAgC;IAChC,IAAI,aAAa,IAAI,MAAM,CAE1B;YAMa,iBAAiB;IAiC/B,mDAAmD;IACnD,OAAO,CAAC,gBAAgB;IA4CxB,2EAA2E;YAC7D,iBAAiB;IA6L/B,4EAA4E;IAC5E,OAAO,CAAC,kBAAkB;IA2C1B,4CAA4C;IAC5C,OAAO,CAAC,sBAAsB;IAkE9B,OAAO,CAAC,eAAe;IA4EvB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAkE5B,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,iBAAiB;IAqBzB,8DAA8D;IAC9D,OAAO,CAAC,iBAAiB;IAQzB,kCAAkC;IAClC;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAsDxB,OAAO,CAAC,QAAQ;IAIhB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAe3B,0CAA0C;IAC1C,OAAO,CAAC,SAAS;CAQlB"}
|