@aws/agentcore 1.0.0-preview.2 → 1.0.0-preview.20

package/dist/schema/schemas/connections.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONNECTION_ID_MAX_LENGTH = exports.ConnectionsSchema = exports.ConnectionSchema = exports.ConnectionTargetSchema = exports.CODE_INTERPRETER_ARN_PATTERN = exports.BROWSER_ARN_PATTERN = exports.GatewayOutboundAuthSchema = exports.GatewayGrantTypeSchema = void 0;
+exports.resourceIdFromArn = resourceIdFromArn;
+exports.connectionIdForTarget = connectionIdForTarget;
+exports.connectionEnvToken = connectionEnvToken;
+exports.connectionTokenFor = connectionTokenFor;
+const zod_1 = require("zod");
+// ============================================================================
+// Resource Connections
+//
+// A connection declares that a principal (an agent runtime or a harness) accesses
+// an EXTERNAL AgentCore resource (a memory/gateway/runtime that is NOT part of this
+// project). The construct generates the correct least-privilege IAM onto the
+// principal's execution role AND injects the discovery env vars from each connection.
+//
+// Connections are embedded on the source resource (AgentEnvSpec.connections /
+// HarnessSpec.connections); the enclosing resource IS the source, so there is no
+// `from` field. In-project access remains implicit (all-to-all wiring) and is
+// untouched — connections only ADD grants for external targets.
+//
+// FUTURE (additive, not in this milestone): targets gain an optional `name` to
+// reference an in-project resource (managed reference + access gating); new target
+// kinds (s3, secret) are added as union members.
+// ============================================================================
+/**
+ * OAuth grant type for an external gateway, matching the runtime/Smithy model.
+ * The harness runtime maps these to AgentCore Identity auth flows:
+ *   CLIENT_CREDENTIALS -> M2M, AUTHORIZATION_CODE -> USER_FEDERATION, TOKEN_EXCHANGE -> TOKEN_EXCHANGE.
+ */
+exports.GatewayGrantTypeSchema = zod_1.z.enum(['CLIENT_CREDENTIALS', 'AUTHORIZATION_CODE', 'TOKEN_EXCHANGE']);
+/**
+ * Outbound auth a caller uses to reach an external gateway. This is the union the
+ * gateway/harness runtime actually consumes — NOT the gateway's inbound authorizerType
+ * (which lives on the gateway resource and is invisible to an external caller).
+ *   - awsIam: SigV4-sign with the execution role (grants InvokeGateway)
+ *   - none:   no auth
+ *   - oauth:  fetch an OAuth token via AgentCore Identity (grants token-fetch perms on
+ *             the provider). All four oauth fields are consumed at runtime.
+ */
+exports.GatewayOutboundAuthSchema = zod_1.z.union([
+    zod_1.z.object({ awsIam: zod_1.z.object({}).strict() }).strict(),
+    zod_1.z.object({ none: zod_1.z.object({}).strict() }).strict(),
+    zod_1.z
+        .object({
+        oauth: zod_1.z
+            .object({
+            providerArn: zod_1.z.string().min(1),
+            scopes: zod_1.z.array(zod_1.z.string().min(1)),
+            grantType: exports.GatewayGrantTypeSchema.optional(),
+            customParameters: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+        })
+            .strict(),
+    })
+        .strict(),
+]);
+// ---- Connection targets (external AgentCore resources, ARN-addressed) ----
+// Partition-agnostic ARN prefix (arn:[^:]+:) per multi-partition rules.
+const MEMORY_ARN_PATTERN = /^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:\d{12}:memory\/.+$/;
+const GATEWAY_ARN_PATTERN = /^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:\d{12}:gateway\/.+$/;
+const RUNTIME_ARN_PATTERN = /^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:\d{12}:runtime\/.+$/;
+// Browser / code-interpreter ARNs come in two legitimate resource-segment forms:
+//   - customer-owned (CreateBrowser/CreateCodeInterpreter): `<kind>-custom/<id>` with a 12-digit account
+//   - AWS-managed default (SYSTEM):                          `<kind>/<id>` with the `aws` account
+exports.BROWSER_ARN_PATTERN = /^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:(\d{12}|aws):browser(-custom)?\/.+$/;
+exports.CODE_INTERPRETER_ARN_PATTERN = /^arn:[^:]+:bedrock-agentcore:[a-z0-9-]+:(\d{12}|aws):code-interpreter(-custom)?\/.+$/;
+const MemoryTargetSchema = zod_1.z
+    .object({
+    type: zod_1.z.literal('memory'),
+    arn: zod_1.z.string().regex(MEMORY_ARN_PATTERN, 'Must be a valid bedrock-agentcore memory ARN'),
+    /** Optional namespace templates to scope List/RetrieveMemoryRecords via the
+     *  bedrock-agentcore:namespace / namespacePath condition keys. */
+    namespaces: zod_1.z.array(zod_1.z.string().min(1)).optional(),
+})
+    .strict();
+const GatewayTargetSchema = zod_1.z
+    .object({
+    type: zod_1.z.literal('gateway'),
+    arn: zod_1.z.string().regex(GATEWAY_ARN_PATTERN, 'Must be a valid bedrock-agentcore gateway ARN'),
+    /** How the caller authenticates outbound to the gateway. Defaults to awsIam (SigV4). */
+    outboundAuth: exports.GatewayOutboundAuthSchema.optional(),
+})
+    .strict();
+const RuntimeTargetSchema = zod_1.z
+    .object({
+    type: zod_1.z.literal('runtime'),
+    arn: zod_1.z.string().regex(RUNTIME_ARN_PATTERN, 'Must be a valid bedrock-agentcore runtime ARN'),
+    /** Also grant InvokeAgentRuntimeCommand (container exec) in addition to invoke. */
+    exec: zod_1.z.boolean().optional(),
+})
+    .strict();
+const BrowserTargetSchema = zod_1.z
+    .object({
+    type: zod_1.z.literal('browser'),
+    /** Customer-owned browser ARN. Omit to use the AWS-managed default browser. */
+    arn: zod_1.z.string().regex(exports.BROWSER_ARN_PATTERN, 'Must be a valid bedrock-agentcore browser ARN').optional(),
+})
+    .strict();
+const CodeInterpreterTargetSchema = zod_1.z
+    .object({
+    type: zod_1.z.literal('codeInterpreter'),
+    /** Customer-owned code-interpreter ARN. Omit to use the AWS-managed default. */
+    arn: zod_1.z
+        .string()
+        .regex(exports.CODE_INTERPRETER_ARN_PATTERN, 'Must be a valid bedrock-agentcore code-interpreter ARN')
+        .optional(),
+})
+    .strict();
+exports.ConnectionTargetSchema = zod_1.z.discriminatedUnion('type', [
+    MemoryTargetSchema,
+    GatewayTargetSchema,
+    RuntimeTargetSchema,
+    BrowserTargetSchema,
+    CodeInterpreterTargetSchema,
+]);
+/**
+ * A single connection from the enclosing principal to an external resource.
+ * `access` is meaningful only for memory (read | readwrite); ignored for invoke-only
+ * targets. Defaults to `read` (least-privilege).
+ */
+exports.ConnectionSchema = zod_1.z
+    .object({
+    id: zod_1.z
+        .string()
+        .regex(/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/, 'Connection id must match [a-zA-Z][a-zA-Z0-9_-]{0,63}')
+        .optional(),
+    to: exports.ConnectionTargetSchema,
+    access: zod_1.z.enum(['read', 'readwrite']).optional(),
+    description: zod_1.z.string().max(200).optional(),
+})
+    .strict();
+exports.ConnectionsSchema = zod_1.z.array(exports.ConnectionSchema);
+// ============================================================================
+// Connection discovery env-var naming — SINGLE SOURCE OF TRUTH.
+//
+// The discovery env var (e.g. MEMORY_<TOKEN>_ID, GATEWAY_<TOKEN>_URL) is the handshake between the
+// CLI export (which bakes the NAME into the generated agent code) and the CDK deploy (which injects
+// the VALUE onto the runtime). Both sides MUST compute the identical <TOKEN>, so the token derivation
+// lives here — the one file already kept in lockstep across the CLI and @aws/agentcore-cdk repos.
+// `connectionEnvToken` is used by `harness-mapper` (CLI) and `connectionTokenFor` by
+// `wire-connections` (CDK); do not re-implement the token derivation. Each side then assembles the
+// final `<PREFIX>_<TOKEN>_<SUFFIX>` name inline (the prefixes/suffixes differ per resource kind).
+// ============================================================================
+/** Maximum length of a connection id (matches the ConnectionSchema id regex bound). */
+exports.CONNECTION_ID_MAX_LENGTH = 64;
+/** Last segment of an ARN (the resource id): `memory/mem-123` -> `mem-123`. */
+function resourceIdFromArn(arn) {
+    const afterColon = arn.split(':').pop() ?? arn;
+    const slash = afterColon.lastIndexOf('/');
+    return slash >= 0 ? afterColon.slice(slash + 1) : afterColon;
+}
+/**
+ * Stable connection id for an external target: `<kind>-<resourceId>`, sanitized to the schema id
+ * charset and length. Used as the connection's `id` AND as the basis for its discovery env-var
+ * token, so the name baked into generated code matches what deploy injects.
+ */
+function connectionIdForTarget(target) {
+    const suffix = 'arn' in target && target.arn ? resourceIdFromArn(target.arn) : target.type;
+    const id = `${target.type}-${suffix}`;
+    // Conform to ConnectionSchema id regex: start with a letter, then [a-zA-Z0-9_-], max length.
+    return id.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, exports.CONNECTION_ID_MAX_LENGTH);
+}
+/** Uppercase, underscore-safe token for env-var naming, derived from a connection id. */
+function connectionEnvToken(id) {
+    return id.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
+/**
+ * Resolve the env-var token for a connection. Prefers the explicit `id`; otherwise derives the same
+ * `<kind>-<resourceId>` id the CLI would have assigned — so an id-less connection (schema permits it,
+ * e.g. a hand-authored config or a direct @aws/agentcore-cdk consumer) yields the SAME token on both
+ * sides instead of diverging.
+ */
+function connectionTokenFor(connection) {
+    return connectionEnvToken(connection.id ?? connectionIdForTarget(connection.to));
+}
+//# sourceMappingURL=connections.js.map

package/dist/schema/schemas/connections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections.js","sourceRoot":"","sources":["../../../src/schema/schemas/connections.ts"],"names":[],"mappings":"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"}