@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.70

package/src/utils/dcr-proxy-constructs/files/project/src/handlers/register.ts.template

@@ -0,0 +1,70 @@
+import type {
+  APIGatewayProxyHandlerV2,
+  APIGatewayProxyStructuredResultV2,
+} from 'aws-lambda';
+
+const COGNITO_CLIENT_ID = process.env.COGNITO_CLIENT_ID!;
+
+interface RegisterRequest {
+  redirect_uris?: unknown;
+  [key: string]: unknown;
+}
+
+function jsonResponse(
+  statusCode: number,
+  body: unknown,
+): APIGatewayProxyStructuredResultV2 {
+  return {
+    statusCode,
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  };
+}
+
+export const handler: APIGatewayProxyHandlerV2 = async (event) => {
+  if (!event.body) {
+    return jsonResponse(400, {
+      error: 'invalid_client_metadata',
+      error_description: 'request body is required',
+    });
+  }
+
+  let req: RegisterRequest;
+  try {
+    req = JSON.parse(event.body) as RegisterRequest;
+  } catch {
+    return jsonResponse(400, {
+      error: 'invalid_client_metadata',
+      error_description: 'request body must be valid JSON',
+    });
+  }
+
+  const redirectUris = req.redirect_uris;
+  if (!Array.isArray(redirectUris) || redirectUris.length === 0) {
+    return jsonResponse(400, {
+      error: 'invalid_redirect_uri',
+      error_description: 'redirect_uris is required and must be a non-empty array',
+    });
+  }
+
+  // The proxy fronts a single Cognito App Client, so Cognito performs the
+  // authoritative check: any redirect_uri forwarded to the Hosted UI must be
+  // registered as a callback URL on that App Client. The proxy only validates
+  // the request shape here and passes the URIs through unchanged.
+  for (const uri of redirectUris) {
+    if (typeof uri !== 'string') {
+      return jsonResponse(400, {
+        error: 'invalid_redirect_uri',
+        error_description: 'each redirect_uri must be a string',
+      });
+    }
+  }
+
+  return jsonResponse(201, {
+    client_id: COGNITO_CLIENT_ID,
+    redirect_uris: redirectUris,
+    token_endpoint_auth_method: 'none',
+    grant_types: ['authorization_code', 'refresh_token'],
+    response_types: ['code'],
+  });
+};

package/src/utils/dcr-proxy-constructs/files/project/src/handlers/token.ts.template

@@ -0,0 +1,75 @@
+import type { APIGatewayProxyHandlerV2 } from 'aws-lambda';
+import {
+  SecretsManagerClient,
+  GetSecretValueCommand,
+} from '@aws-sdk/client-secrets-manager';
+
+const COGNITO_HOSTED_UI_BASE = process.env.COGNITO_HOSTED_UI_BASE!;
+const COGNITO_CLIENT_ID = process.env.COGNITO_CLIENT_ID!;
+const COGNITO_CLIENT_SECRET_ARN = process.env.COGNITO_CLIENT_SECRET_ARN!;
+const COGNITO_REGION = process.env.COGNITO_REGION!;
+
+const sm = new SecretsManagerClient({ region: COGNITO_REGION });
+let cachedSecret: string | undefined;
+
+async function getClientSecret(): Promise<string> {
+  if (cachedSecret) return cachedSecret;
+  const res = await sm.send(
+    new GetSecretValueCommand({ SecretId: COGNITO_CLIENT_SECRET_ARN }),
+  );
+  if (!res.SecretString) {
+    throw new Error('client_secret missing in Secrets Manager');
+  }
+  cachedSecret = res.SecretString;
+  return cachedSecret;
+}
+
+export const handler: APIGatewayProxyHandlerV2 = async (event) => {
+  if (!event.body) {
+    return {
+      statusCode: 400,
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        error: 'invalid_request',
+        error_description: 'request body is required',
+      }),
+    };
+  }
+
+  const rawBody = event.isBase64Encoded
+    ? Buffer.from(event.body, 'base64').toString('utf-8')
+    : event.body;
+
+  const params = new URLSearchParams(rawBody);
+
+  // Always force the real Cognito client_id and inject the server-side secret.
+  // DCR returned the same client_id to every caller, but we re-assert here
+  // to keep client_id/secret consistent regardless of what the caller sent.
+  params.set('client_id', COGNITO_CLIENT_ID);
+  params.set('client_secret', await getClientSecret());
+
+  // Cognito does not understand RFC 8707 `resource`; some MCP clients send it
+  // and Cognito has been observed to reject the exchange when present.
+  params.delete('resource');
+
+  const res = await fetch(`${COGNITO_HOSTED_UI_BASE}/oauth2/token`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: params.toString(),
+  });
+
+  const responseBody = await res.text();
+  console.log('[token]', {
+    grant_type: params.get('grant_type'),
+    status: res.status,
+    ...(res.ok ? {} : { body: responseBody }),
+  });
+
+  return {
+    statusCode: res.status,
+    headers: {
+      'content-type': res.headers.get('content-type') ?? 'application/json',
+    },
+    body: responseBody,
+  };
+};

package/src/utils/dcr-proxy-constructs/files/terraform/app/dcr-proxies/__nameKebabCase__/__nameKebabCase__.tf.template

@@ -0,0 +1,410 @@
+# OAuth Dynamic Client Registration (DCR) proxy for Amazon Cognito.
+#
+# Lets MCP clients (Claude Code, Kiro CLI, MCP Inspector, ...) authenticate
+# against an Amazon Cognito User Pool while keeping the Hosted UI flow intact,
+# supporting RFC 7591 Dynamic Client Registration, and never exposing the
+# Cognito App Client secret to the client.
+
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "<%- awsProviderVersion %>"
+    }
+    archive = {
+      source  = "hashicorp/archive"
+      version = "<%- archiveProviderVersion %>"
+    }
+  }
+}
+
+# Cognito configuration (injected by the caller)
+variable "user_pool_id" {
+  description = "Cognito User Pool id (e.g. us-east-1_abc123)"
+  type        = string
+}
+
+variable "user_pool_client_id" {
+  description = "Cognito User Pool App Client id"
+  type        = string
+}
+
+variable "cognito_client_secret_arn" {
+  description = "ARN of the Secrets Manager secret holding the Cognito App Client secret. The token handler reads this at runtime; the secret is never exposed to the client."
+  type        = string
+}
+
+variable "cognito_hosted_ui_base" {
+  description = "Base URL of the Cognito Hosted UI domain, without a trailing slash (e.g. https://my-domain.auth.us-east-1.amazoncognito.com)"
+  type        = string
+}
+
+variable "upstream_url" {
+  description = "Full URL of the upstream MCP server. The proxy forwards /mcp requests to this URL and rewrites the upstream WWW-Authenticate header."
+  type        = string
+}
+
+variable "env" {
+  description = "Additional environment variables applied to all proxy Lambda functions"
+  type        = map(string)
+  default     = {}
+}
+
+# CORS Configuration (passed to the core http-api module)
+variable "cors_allow_headers" {
+  description = "List of allowed headers for CORS"
+  type        = list(string)
+  default     = ["authorization", "content-type", "mcp-protocol-version"]
+}
+
+variable "cors_allow_methods" {
+  description = "List of allowed HTTP methods for CORS"
+  type        = list(string)
+  default     = ["GET", "POST", "DELETE", "OPTIONS"]
+}
+
+variable "cors_allow_origins" {
+  description = "List of allowed origins for CORS"
+  type        = list(string)
+  default     = ["*"]
+}
+
+variable "asset_bucket_name" {
+  description = "Name of the shared asset S3 bucket used to stage the Lambda deployment zips. Instantiate the `core/asset-bucket` module once per deployment and pass its `bucket_name` output here."
+  type        = string
+}
+
+variable "mcp_proxy_timeout" {
+  description = "Timeout (seconds) applied to the MCP proxy Lambda. Defaults to 29 (the API Gateway HTTP API integration limit)."
+  type        = number
+  default     = 29
+}
+
+variable "mcp_proxy_memory_size" {
+  description = "Memory size (MB) for the MCP proxy Lambda"
+  type        = number
+  default     = 512
+}
+
+variable "tags" {
+  description = "Tags to apply to all resources"
+  type        = map(string)
+  default     = {}
+}
+
+data "aws_region" "current" {}
+data "aws_caller_identity" "current" {}
+
+# The Cognito App Client secret, referenced by ARN so the token handler's role
+# can be scoped to read exactly this secret.
+data "aws_secretsmanager_secret" "cognito_client_secret" {
+  arn = var.cognito_client_secret_arn
+}
+
+resource "random_string" "suffix" {
+  length  = 8
+  special = false
+  upper   = false
+}
+
+locals {
+  aws_account_id = data.aws_caller_identity.current.account_id
+  aws_region     = data.aws_region.current.region
+
+  base_env = merge({
+    COGNITO_CLIENT_ID         = var.user_pool_client_id
+    COGNITO_CLIENT_SECRET_ARN = var.cognito_client_secret_arn
+    COGNITO_ISSUER            = "https://cognito-idp.${local.aws_region}.amazonaws.com/${var.user_pool_id}"
+    COGNITO_HOSTED_UI_BASE    = var.cognito_hosted_ui_base
+    COGNITO_REGION            = local.aws_region
+  }, var.env)
+
+  # Workspace-root-relative bundle output directory per handler
+  handler_bundle_dirs = {
+    "protected-resource-metadata"   = "<%- bundlePathsFromRoot['protected-resource-metadata'] %>"
+    "authorization-server-metadata" = "<%- bundlePathsFromRoot['authorization-server-metadata'] %>"
+    "register"                      = "<%- bundlePathsFromRoot['register'] %>"
+    "authorize"                     = "<%- bundlePathsFromRoot['authorize'] %>"
+    "token"                         = "<%- bundlePathsFromRoot['token'] %>" #checkov:skip=CKV_SECRET_6:Value is a Lambda bundle output path, not a secret
+    "mcp-proxy"                     = "<%- bundlePathsFromRoot['mcp-proxy'] %>"
+  }
+
+  # Handlers deployed with the standard configuration (timeout 10s, mem 256).
+  # mcp-proxy is deployed separately since its env/timeout/memory differ.
+  standard_handlers = {
+    for name, dir in local.handler_bundle_dirs : name => dir if name != "mcp-proxy"
+  }
+}
+
+# Package each handler's rolldown bundle into a deployment zip
+data "archive_file" "handler_zip" {
+  for_each = local.handler_bundle_dirs
+
+  type        = "zip"
+  source_dir  = "${path.module}/../../../../../../../${each.value}"
+  output_path = "${path.module}/../../../../../../../dist/packages/common/terraform/dcr-proxies/<%- nameKebabCase %>/${each.key}/lambda.zip"
+}
+
+resource "aws_s3_object" "handler_zip" {
+  for_each = local.handler_bundle_dirs
+
+  bucket      = var.asset_bucket_name
+  key         = "dcr-proxies/<%- nameKebabCase %>/${each.key}/${data.archive_file.handler_zip[each.key].output_sha256}.zip"
+  source      = data.archive_file.handler_zip[each.key].output_path
+  source_hash = data.archive_file.handler_zip[each.key].output_base64sha256
+  etag        = data.archive_file.handler_zip[each.key].output_md5
+}
+
+# Shared execution role for handlers that do not read the client secret
+resource "aws_iam_role" "proxy" {
+  name = "<%- nameKebabCase %>-proxy-${random_string.suffix.result}"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect    = "Allow"
+      Principal = { Service = "lambda.amazonaws.com" }
+      Action    = "sts:AssumeRole"
+    }]
+  })
+
+  tags = var.tags
+}
+
+# Dedicated role for the token handler, additionally granted read access to the
+# Cognito App Client secret only.
+resource "aws_iam_role" "token" {
+  name = "<%- nameKebabCase %>-token-${random_string.suffix.result}"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect    = "Allow"
+      Principal = { Service = "lambda.amazonaws.com" }
+      Action    = "sts:AssumeRole"
+    }]
+  })
+
+  tags = var.tags
+}
+
+resource "aws_iam_role_policy_attachment" "proxy_basic" {
+  role       = aws_iam_role.proxy.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+}
+
+resource "aws_iam_role_policy_attachment" "proxy_xray" {
+  role       = aws_iam_role.proxy.name
+  policy_arn = "arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess"
+}
+
+resource "aws_iam_role_policy_attachment" "token_basic" {
+  role       = aws_iam_role.token.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+}
+
+resource "aws_iam_role_policy_attachment" "token_xray" {
+  role       = aws_iam_role.token.name
+  policy_arn = "arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess"
+}
+
+resource "aws_iam_role_policy" "token_secret_read" {
+  name = "<%- nameKebabCase %>-token-secret-read-${random_string.suffix.result}"
+  role = aws_iam_role.token.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = ["secretsmanager:GetSecretValue"]
+      Resource = [data.aws_secretsmanager_secret.cognito_client_secret.arn]
+    }]
+  })
+}
+
+# Standard handler Lambda functions
+resource "aws_lambda_function" "standard" {
+  #checkov:skip=CKV_AWS_117:Lambda does not need to be in a VPC for this use case
+  #checkov:skip=CKV_AWS_116:Dead Letter Queue not required for this use case
+  #checkov:skip=CKV_AWS_272:Code signing not required for this use case
+  #checkov:skip=CKV_AWS_115:Concurrent execution limit not required for this use case
+  #checkov:skip=CKV_AWS_173:Lambda environment variables encrypted by managed key
+  for_each = local.standard_handlers
+
+  s3_bucket        = aws_s3_object.handler_zip[each.key].bucket
+  s3_key           = aws_s3_object.handler_zip[each.key].key
+  function_name    = "<%- nameKebabCase %>-${each.key}-${random_string.suffix.result}"
+  role             = each.key == "token" ? aws_iam_role.token.arn : aws_iam_role.proxy.arn
+  handler          = "index.handler"
+  runtime          = "nodejs22.x"
+  architectures    = ["arm64"]
+  source_code_hash = data.archive_file.handler_zip[each.key].output_base64sha256
+  timeout          = 10
+  memory_size      = 256
+
+  tracing_config {
+    mode = "Active"
+  }
+
+  environment {
+    variables = local.base_env
+  }
+
+  tags = var.tags
+}
+
+# MCP proxy Lambda function (extended env, timeout and memory)
+resource "aws_lambda_function" "mcp_proxy" {
+  #checkov:skip=CKV_AWS_117:Lambda does not need to be in a VPC for this use case
+  #checkov:skip=CKV_AWS_116:Dead Letter Queue not required for this use case
+  #checkov:skip=CKV_AWS_272:Code signing not required for this use case
+  #checkov:skip=CKV_AWS_115:Concurrent execution limit not required for this use case
+  #checkov:skip=CKV_AWS_173:Lambda environment variables encrypted by managed key
+  s3_bucket        = aws_s3_object.handler_zip["mcp-proxy"].bucket
+  s3_key           = aws_s3_object.handler_zip["mcp-proxy"].key
+  function_name    = "<%- nameKebabCase %>-mcp-proxy-${random_string.suffix.result}"
+  role             = aws_iam_role.proxy.arn
+  handler          = "index.handler"
+  runtime          = "nodejs22.x"
+  architectures    = ["arm64"]
+  source_code_hash = data.archive_file.handler_zip["mcp-proxy"].output_base64sha256
+  timeout          = var.mcp_proxy_timeout
+  memory_size      = var.mcp_proxy_memory_size
+
+  tracing_config {
+    mode = "Active"
+  }
+
+  environment {
+    variables = merge(local.base_env, {
+      UPSTREAM_URL       = var.upstream_url
+      PROXY_METADATA_URL = "${module.http_api.api_endpoint}/.well-known/oauth-protected-resource"
+    })
+  }
+
+  tags = var.tags
+}
+
+# HTTP API Gateway (shared core module)
+module "http_api" {
+  source = "../../../core/api/http-api"
+
+  api_name           = "<%- nameKebabCase %>-mcp-auth-proxy-${random_string.suffix.result}"
+  api_description    = "MCP-compatible OAuth proxy for Amazon Cognito"
+  stage_name         = "$default"
+  stage_auto_deploy  = true
+  cors_allow_headers = var.cors_allow_headers
+  cors_allow_methods = var.cors_allow_methods
+  cors_allow_origins = var.cors_allow_origins
+
+  tags = var.tags
+}
+
+# Integrations
+resource "aws_apigatewayv2_integration" "standard" {
+  for_each = local.standard_handlers
+
+  api_id                 = module.http_api.api_id
+  integration_type       = "AWS_PROXY"
+  integration_uri        = aws_lambda_function.standard[each.key].invoke_arn
+  payload_format_version = "2.0"
+  timeout_milliseconds   = 30000
+}
+
+resource "aws_apigatewayv2_integration" "mcp_proxy" {
+  api_id                 = module.http_api.api_id
+  integration_type       = "AWS_PROXY"
+  integration_uri        = aws_lambda_function.mcp_proxy.invoke_arn
+  payload_format_version = "2.0"
+  timeout_milliseconds   = 29000
+}
+
+# Routes. jwks_uri/issuer are handled by Cognito; the proxy hosts the OAuth
+# metadata, authorize, token and registration endpoints plus the /mcp proxy.
+locals {
+  routes = {
+    "GET /.well-known/oauth-protected-resource"   = "protected-resource-metadata"
+    "GET /.well-known/oauth-authorization-server" = "authorization-server-metadata"
+    "GET /.well-known/openid-configuration"       = "authorization-server-metadata"
+    "POST /register"                              = "register"
+    "GET /authorize"                              = "authorize"
+    "POST /oauth/token"                           = "token"
+  }
+}
+
+# OAuth discovery, registration and authorization endpoints are part of the
+# public DCR/OAuth flow and must be reachable without prior authorization.
+resource "aws_apigatewayv2_route" "standard" {
+  #checkov:skip=CKV_AWS_309:Public OAuth/DCR endpoints must be accessible without authorization
+  for_each = local.routes
+
+  api_id             = module.http_api.api_id
+  route_key          = each.key
+  target             = "integrations/${aws_apigatewayv2_integration.standard[each.value].id}"
+  authorization_type = "NONE"
+}
+
+# The /mcp route enforces authorization at the upstream MCP server, so the
+# proxy route itself is intentionally left open.
+resource "aws_apigatewayv2_route" "mcp_proxy" {
+  #checkov:skip=CKV_AWS_309:Authorization is enforced by the upstream MCP server, not this proxy route
+  api_id             = module.http_api.api_id
+  route_key          = "ANY /mcp"
+  target             = "integrations/${aws_apigatewayv2_integration.mcp_proxy.id}"
+  authorization_type = "NONE"
+}
+
+# Permissions for API Gateway to invoke each Lambda
+resource "aws_lambda_permission" "standard" {
+  for_each = local.standard_handlers
+
+  statement_id  = "AllowAPIGatewayInvoke"
+  action        = "lambda:InvokeFunction"
+  function_name = aws_lambda_function.standard[each.key].function_name
+  principal     = "apigateway.amazonaws.com"
+  source_arn    = "${module.http_api.api_execution_arn}/*/*"
+}
+
+resource "aws_lambda_permission" "mcp_proxy" {
+  statement_id  = "AllowAPIGatewayInvoke"
+  action        = "lambda:InvokeFunction"
+  function_name = aws_lambda_function.mcp_proxy.function_name
+  principal     = "apigateway.amazonaws.com"
+  source_arn    = "${module.http_api.api_execution_arn}/*/*"
+}
+
+# Outputs
+output "proxy_url" {
+  description = "Base URL of the DCR proxy"
+  value       = module.http_api.api_endpoint
+}
+
+output "mcp_url" {
+  description = "MCP endpoint proxied to the upstream server"
+  value       = "${module.http_api.api_endpoint}/mcp"
+}
+
+output "metadata_url" {
+  description = "OAuth protected-resource metadata URL"
+  value       = "${module.http_api.api_endpoint}/.well-known/oauth-protected-resource"
+}
+
+output "auth_server_metadata_url" {
+  description = "OAuth authorization-server metadata URL"
+  value       = "${module.http_api.api_endpoint}/.well-known/oauth-authorization-server"
+}
+
+output "token_endpoint" {
+  description = "OAuth token endpoint"
+  value       = "${module.http_api.api_endpoint}/oauth/token"
+}
+
+output "registration_endpoint" {
+  description = "Dynamic Client Registration endpoint"
+  value       = "${module.http_api.api_endpoint}/register"
+}
+
+output "api_id" {
+  description = "ID of the HTTP API Gateway"
+  value       = module.http_api.api_id
+}

package/src/utils/declared-dependencies.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IPyDepVersion, ITsDepVersion } from './versions';
+/**
+ * Which vended dependencies each generator is responsible for, and when each
+ * applies.
+ *
+ * A generator declares every dependency it may add — including those added on
+ * its behalf by helpers it calls — once, and `addTsDependencies` /
+ * `addPyDependencies` add the subset whose `when` predicate the generator's
+ * metadata satisfies. The declaration is the only place packages are listed.
+ *
+ * The same declaration drives the version sync migration, which replays the
+ * predicates against the metadata recorded on each project. Pass the very object
+ * you record as metadata, so what a generator added and what the migration owns
+ * cannot drift.
+ */
+/**
+ * The metadata a generator records, which its predicates read. Deliberately
+ * `object` rather than an index signature, so a generator can type its
+ * declaration against a plain interface.
+ */
+export type DependencyMetadata = object;
+/** What every declared dependency carries, whichever language it belongs to. */
+export interface DeclaredDependency<Name, M extends DependencyMetadata> {
+    readonly name: Name;
+    /**
+     * Whether this dependency applies. Reads the metadata the generator records,
+     * so the migration can evaluate the same predicate later. Any truthy return
+     * counts, so a predicate can hand back the value it read.
+     */
+    readonly when?: (metadata: M) => unknown;
+    /** Added to the workspace root manifest rather than the project's. */
+    readonly root?: boolean;
+    /**
+     * Declared only so the version sync keeps its pinned version current — an
+     * `overrides` entry, say. Never installed as a dependency.
+     */
+    readonly versionOnly?: boolean;
+}
+/**
+ * A TypeScript dependency, which may be a dev dependency.
+ *
+ * `group` is typed as never-present rather than left off, so putting a Python
+ * flag on a TypeScript entry is a type error instead of an ignored property.
+ */
+export interface DeclaredTsDependency<Name, M extends DependencyMetadata> extends DeclaredDependency<Name, M> {
+    /** Added as a dev dependency rather than a runtime one. */
+    readonly dev?: boolean;
+    readonly group?: never;
+}
+/** A Python dependency, which may belong to a pyproject dependency group. */
+export interface DeclaredPyDependency<Name, M extends DependencyMetadata> extends DeclaredDependency<Name, M> {
+    /** Added to this pyproject dependency group rather than the main list. */
+    readonly group?: string;
+    readonly dev?: never;
+}
+export interface DependencyDeclaration<Ts extends readonly DeclaredTsDependency<ITsDepVersion, never>[] = readonly DeclaredTsDependency<ITsDepVersion, never>[], Py extends readonly DeclaredPyDependency<IPyDepVersion, never>[] = readonly DeclaredPyDependency<IPyDepVersion, never>[]> {
+    readonly ts: Ts;
+    readonly py: Py;
+}
+/**
+ * Declare the dependencies a generator owns, typed against the metadata it
+ * records. Spread the `*_DEPENDENCIES` of any helper called, so the declaration
+ * covers what those helpers add too.
+ */
+export declare const declareDependencies: <M extends DependencyMetadata = Record<string, never>>() => <const Ts extends readonly DeclaredTsDependency<ITsDepVersion, M>[], const Py extends readonly DeclaredPyDependency<IPyDepVersion, M>[]>(declaration: {
+    ts?: Ts;
+    py?: Py;
+}) => DependencyDeclaration<Ts, Py>;
+/**
+ * Narrow entries to a further condition, keeping the one each already carries.
+ *
+ * For a helper's constant spread into a generator that calls it down one branch:
+ * the branch gates the whole set, and each entry's own predicate still gates it
+ * within that branch. Replacing `when` outright would widen ownership to the
+ * helper's every branch.
+ */
+export declare const onlyWhen: <M extends DependencyMetadata, const Entries extends readonly {
+    readonly name: unknown;
+}[]>(entries: Entries, condition: (metadata: M) => unknown) => { readonly [K in keyof Entries]: Omit<Entries[K], "when"> & {
+    when: (m: M) => boolean;
+}; };
+/**
+ * Mark entries as declared for ownership but never installed here — a helper's
+ * constant spread into a generator that doesn't own the project the helper adds
+ * them to.
+ */
+export declare const ownedElsewhere: <const Entries extends readonly unknown[]>(entries: Entries) => { readonly [K in keyof Entries]: Entries[K] & {
+    versionOnly: true;
+}; };
+/** Every package a declaration names, whatever its predicate. */
+export declare const declaredNames: <Name>(entries: readonly {
+    readonly name: Name;
+}[]) => Name[];
+/**
+ * The entries of a declaration whose condition the given metadata satisfies —
+ * everything this occurrence is responsible for, installed here or not.
+ *
+ * A predicate that throws — reading a field the metadata doesn't carry, say —
+ * counts as not applying. The migration evaluates these against whatever a
+ * project happened to record, and must not claim a branch it cannot confirm.
+ */
+export declare const ownedDependencyEntries: <Name, M extends DependencyMetadata, Entry extends DeclaredDependency<Name, M>>(entries: readonly Entry[], metadata: M) => Entry[];
+/**
+ * The entries to install for the given metadata: those it owns, less the ones
+ * declared for their version alone. A `versionOnly` entry is still owned — the
+ * sync keeps its pin current wherever it already sits.
+ */
+export declare const applicableDependencies: <Name, M extends DependencyMetadata, Entry extends DeclaredDependency<Name, M>>(entries: readonly Entry[], metadata: M) => Entry[];
+/**
+ * Requires a caller's declaration to cover `Needed`, naming whatever is missing
+ * in the type error. Helpers that add dependencies take this alongside the
+ * declaration so a forgotten spread can't compile.
+ */
+export type MustDeclare<Needed extends readonly {
+    readonly name: ITsDepVersion;
+}[], D extends DependencyDeclaration> = [Exclude<Needed[number]['name'], D['ts'][number]['name']>] extends [never] ? unknown : {
+    __missingDeclaredDependencies: Exclude<Needed[number]['name'], D['ts'][number]['name']>;
+};
+/** `MustDeclare` for Python dependencies. */
+export type MustDeclarePy<Needed extends readonly {
+    readonly name: IPyDepVersion;
+}[], D extends DependencyDeclaration> = [Exclude<Needed[number]['name'], D['py'][number]['name']>] extends [never] ? unknown : {
+    __missingDeclaredPyDependencies: Exclude<Needed[number]['name'], D['py'][number]['name']>;
+};
+/**
+ * The dependencies a declaration covers, for typing a conditional list without
+ * widening it to every vended package.
+ */
+export type DeclaredTs<D extends DependencyDeclaration> = D['ts'][number]['name'];
+/** `DeclaredTs` for Python dependencies. */
+export type DeclaredPy<D extends DependencyDeclaration> = D['py'][number]['name'];
+/**
+ * Narrows a caller's declaration to the subset a helper adds, which
+ * `MustDeclare` has already proven the caller covers.
+ */
+export declare const forDependencies: <const Ts extends readonly DeclaredDependency<ITsDepVersion, never>[] = [], const Py extends readonly DeclaredDependency<IPyDepVersion, never>[] = []>(declaration: DependencyDeclaration) => DependencyDeclaration<Ts, Py>;